Add Template Examples (#1459)

* Adding notebooks to display the different templates in the Panel Reference Gallery

* adding theming information to the Template Reference notebooks

* removing notebook metadata

* adding a templates section to references in conf.py

* adding information about panel template use to the reference notebooks

* adding information about the slightly different usage of GoldenTemplate

* Add indicators to reference gallery

* adding a templates section to references in conf.py

* Update docs

* Added screenshots

Co-authored-by: Philipp Rudiger <prudiger@anaconda.com>

doc/conf.py

@@ -73,8 +73,9 @@
             'sections': [
                 'panes',
                 'layouts',
+                'templates'
                 'indicators',
-                'widgets'
+                'widgets',
             ]
         }
     },

examples/reference/templates/Bootstrap.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import panel as pn\n",
+    "import numpy as np\n",
+    "import holoviews as hv\n",
+    "\n",
+    "pn.extension()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For a large variety of use cases we do not need complete control over the exact layout of each individual component on the page, as could be achieved with a [custom template](../../user_guide/Templates.ipynb), we just want to achieve a more polished look and feel. For these cases Panel ships with a number of default templates, which are defined by declaring three main content areas on the page, which can be populated as desired:\n",
+    "\n",
+    "* **`header`**: The header area of the HTML page\n",
+    "* **`sidebar`**: A collapsible sidebar\n",
+    "* **`main`**: The main area of the application\n",
+    "* **`modal`**: A modal area which can be opened and closed from Python\n",
+    "\n",
+    "These three areas behave very similarly to other Panel layout components and have list-like semantics. This means we can easily append new components into these areas. Unlike other layout components however, the contents of the areas is fixed once rendered. If you need a dynamic layout you should therefore insert a regular Panel layout component (e.g. a `Column` or `Row`) and modify it in place once added to one of the content areas. \n",
+    "\n",
+    "Templates can allow for us to quickly and easily create web apps for displaying our data. Panel comes with a default Template, and includes multiple Templates that extend the default which add some customization for a better display.\n",
+    "\n",
+    "#### Parameters:\n",
+    "\n",
+    "In addition to the four different areas we can populate the default templates also provide a few additional parameters:\n",
+    "\n",
+    "* **`busy_indicator`** (BooleanIndicator): Visual indicator of application busy state.\n",
+    "* **`header_background`** (str): Optional header background color override.\n",
+    "* **`header_color`** (str): Optional header text color override.\n",
+    "* **`theme`** (Theme): A Theme class (available in `panel.template.theme`)\n",
+    "* **`title`** (str): A title to show in the header.\n",
+    "\n",
+    "________"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this case we are using the `BootstrapTemplate`, built on  [Bootstrap v4](https://getbootstrap.com/docs/4.0/getting-started/introduction/), which is a light weight CSS framework. Here is an example of how you can set up a display using this template:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bootstrap = pn.template.BootstrapTemplate(title='Bootstrap Template')\n",
+    "\n",
+    "pn.config.sizing_mode = 'stretch_width'\n",
+    "\n",
+    "xs = np.linspace(0, np.pi)\n",
+    "freq = pn.widgets.FloatSlider(name=\"Frequency\", start=0, end=10, value=2)\n",
+    "phase = pn.widgets.FloatSlider(name=\"Phase\", start=0, end=np.pi)\n",
+    "\n",
+    "@pn.depends(freq=freq, phase=phase)\n",
+    "def sine(freq, phase):\n",
+    "    return hv.Curve((xs, np.sin(xs*freq+phase))).opts(\n",
+    "        responsive=True, min_height=400)\n",
+    "\n",
+    "@pn.depends(freq=freq, phase=phase)\n",
+    "def cosine(freq, phase):\n",
+    "    return hv.Curve((xs, np.cos(xs*freq+phase))).opts(\n",
+    "        responsive=True, min_height=400)\n",
+    "\n",
+    "bootstrap.sidebar.append(freq)\n",
+    "bootstrap.sidebar.append(phase)\n",
+    "\n",
+    "bootstrap.main.append(\n",
+    "    pn.Row(\n",
+    "        pn.Card(hv.DynamicMap(sine), title='Sine'),\n",
+    "        pn.Card(hv.DynamicMap(cosine), title='Cosine')\n",
+    "    )\n",
+    ")\n",
+    "bootstrap.servable();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<h3><b>BootstrapTemplate with DefaultTheme</b></h3>\n",
+    "<img src=\"../../assets/Bootstrap.png\" style=\"margin-left: auto; margin-right: auto; display: block;\"></img>\n",
+    "</br>    \n",
+    "<h3><b>BootstrapTemplate with DarkTheme</b></h3>\n",
+    "<img src=\"../../assets/BootstrapDark.png\" style=\"margin-left: auto; margin-right: auto; display: block;\"></img>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The app can be displayed within the notebook by using `.servable()`, or rendered in another tab by replacing it with `.show()`. \n",
+    "\n",
+    "Themes can be added using the optional keyword argument `theme`. Each template comes with a DarkTheme and a DefaultTheme, which can be set `BootstrapTemplate(theme=DarkTheme)`. If no theme is set, then DefaultTheme will be applied.\n",
+    "\n",
+    "It should be noted that Templates may not render correctly in a notebook, and for the best performance the should ideally be deployed to a server."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

examples/reference/templates/GoldenLayout.ipynb

@@ -0,0 +1,125 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import panel as pn\n",
+    "import numpy as np\n",
+    "import holoviews as hv\n",
+    "\n",
+    "pn.extension()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For a large variety of use cases we do not need complete control over the exact layout of each individual component on the page, as could be achieved with a [custom template](../../user_guide/Templates.ipynb), we just want to achieve a more polished look and feel. For these cases Panel ships with a number of default templates, which are defined by declaring three main content areas on the page, which can be populated as desired:\n",
+    "\n",
+    "* **`header`**: The header area of the HTML page\n",
+    "* **`sidebar`**: A collapsible sidebar\n",
+    "* **`main`**: The main area of the application\n",
+    "* **`modal`**: A modal area which can be opened and closed from Python\n",
+    "\n",
+    "These three areas behave very similarly to other Panel layout components and have list-like semantics. This means we can easily append new components into these areas. Unlike other layout components however, the contents of the areas is fixed once rendered. If you need a dynamic layout you should therefore insert a regular Panel layout component (e.g. a `Column` or `Row`) and modify it in place once added to one of the content areas. \n",
+    "\n",
+    "Templates can allow for us to quickly and easily create web apps for displaying our data. Panel comes with a default Template, and includes multiple Templates that extend the default which add some customization for a better display.\n",
+    "\n",
+    "#### Parameters:\n",
+    "\n",
+    "In addition to the four different areas we can populate the default templates also provide a few additional parameters:\n",
+    "\n",
+    "* **`busy_indicator`** (BooleanIndicator): Visual indicator of application busy state.\n",
+    "* **`header_background`** (str): Optional header background color override.\n",
+    "* **`header_color`** (str): Optional header text color override.\n",
+    "* **`theme`** (Theme): A Theme class (available in `panel.template.theme`)\n",
+    "* **`title`** (str): A title to show in the header.\n",
+    "\n",
+    "________"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this case we are using the `GoldenTemplate`, built using the Golden Layout CSS, which allows for the creation of tabs that can be moved around. Due to the movable tabs this Template is a little different than the others. The sidebar works similarly to the other templates, but to have your displays render in different tabs, we have to make separate calls to `<template_name>.main.append()`. Here is an example of how you can set up a display using this template:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "golden = pn.template.GoldenTemplate(title='Golden Template')\n",
+    "\n",
+    "pn.config.sizing_mode = 'stretch_width'\n",
+    "\n",
+    "xs = np.linspace(0, np.pi)\n",
+    "freq = pn.widgets.FloatSlider(name=\"Frequency\", start=0, end=10, value=2)\n",
+    "phase = pn.widgets.FloatSlider(name=\"Phase\", start=0, end=np.pi)\n",
+    "\n",
+    "@pn.depends(freq=freq, phase=phase)\n",
+    "def sine(freq, phase):\n",
+    "    return hv.Curve((xs, np.sin(xs*freq+phase))).opts(\n",
+    "        responsive=True, min_height=400)\n",
+    "\n",
+    "@pn.depends(freq=freq, phase=phase)\n",
+    "def cosine(freq, phase):\n",
+    "    return hv.Curve((xs, np.cos(xs*freq+phase))).opts(\n",
+    "        responsive=True, min_height=400)\n",
+    "\n",
+    "golden.sidebar.append(freq)\n",
+    "golden.sidebar.append(phase)\n",
+    "\n",
+    "golden.main.append(\n",
+    "    pn.Row(\n",
+    "        pn.Card(hv.DynamicMap(sine), title='Sine'),\n",
+    "        pn.Card(hv.DynamicMap(cosine), title='Cosine')\n",
+    "    )\n",
+    ")\n",
+    "golden.main.append(\n",
+    "    pn.Row(\n",
+    "        pn.Card(hv.DynamicMap(sine), title='Sine'),\n",
+    "        pn.Card(hv.DynamicMap(cosine), title='Cosine')\n",
+    "    )\n",
+    ")\n",
+    "\n",
+    "golden.servable();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<h3><b>GoldenTemplate with DefaultTheme</b></h3>\n",
+    "<img src=\"../../assets/Golden.png\" style=\"margin-left: auto; margin-right: auto; display: block;\"></img>\n",
+    "</br>    \n",
+    "<h3><b>GoldenTemplate with DarkTheme</b></h3>\n",
+    "<img src=\"../../assets/GoldenDark.png\" style=\"margin-left: auto; margin-right: auto; display: block;\"></img>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The app can be displayed within the notebook by using `.servable()`, or rendered in another tab by replacing it with `.show()`. \n",
+    "\n",
+    "Themes can be added using the optional keyword argument `theme`. Each template comes with a DarkTheme and a DefaultTheme, which can be set `GoldenTemplate(theme=DarkTheme)`. If no theme is set, then DefaultTheme will be applied.\n",
+    "\n",
+    "It should be noted that Templates may not render correctly in a notebook, and for the best performance the should ideally be deployed to a server."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

examples/reference/templates/Material.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import panel as pn\n",
+    "import numpy as np\n",
+    "import holoviews as hv\n",
+    "\n",
+    "pn.extension()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For a large variety of use cases we do not need complete control over the exact layout of each individual component on the page, as could be achieved with a [custom template](../../user_guide/Templates.ipynb), we just want to achieve a more polished look and feel. For these cases Panel ships with a number of default templates, which are defined by declaring three main content areas on the page, which can be populated as desired:\n",
+    "\n",
+    "* **`header`**: The header area of the HTML page\n",
+    "* **`sidebar`**: A collapsible sidebar\n",
+    "* **`main`**: The main area of the application\n",
+    "* **`modal`**: A modal area which can be opened and closed from Python\n",
+    "\n",
+    "These three areas behave very similarly to other Panel layout components and have list-like semantics. This means we can easily append new components into these areas. Unlike other layout components however, the contents of the areas is fixed once rendered. If you need a dynamic layout you should therefore insert a regular Panel layout component (e.g. a `Column` or `Row`) and modify it in place once added to one of the content areas. \n",
+    "\n",
+    "Templates can allow for us to quickly and easily create web apps for displaying our data. Panel comes with a default Template, and includes multiple Templates that extend the default which add some customization for a better display.\n",
+    "\n",
+    "#### Parameters:\n",
+    "\n",
+    "In addition to the four different areas we can populate the default templates also provide a few additional parameters:\n",
+    "\n",
+    "* **`busy_indicator`** (BooleanIndicator): Visual indicator of application busy state.\n",
+    "* **`header_background`** (str): Optional header background color override.\n",
+    "* **`header_color`** (str): Optional header text color override.\n",
+    "* **`theme`** (Theme): A Theme class (available in `panel.template.theme`)\n",
+    "* **`title`** (str): A title to show in the header.\n",
+    "\n",
+    "________"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this case we are using the `MaterialTemplate`, built on [Material Components for the web](https://material.io/develop/web/), which is a CSS framework that provides a lot of built in stylings to create a smooth layout. Here is an example of how you can set up a display using this template:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "material = pn.template.MaterialTemplate(title='Material Template')\n",
+    "\n",
+    "pn.config.sizing_mode = 'stretch_width'\n",
+    "\n",
+    "xs = np.linspace(0, np.pi)\n",
+    "freq = pn.widgets.FloatSlider(name=\"Frequency\", start=0, end=10, value=2)\n",
+    "phase = pn.widgets.FloatSlider(name=\"Phase\", start=0, end=np.pi)\n",
+    "\n",
+    "@pn.depends(freq=freq, phase=phase)\n",
+    "def sine(freq, phase):\n",
+    "    return hv.Curve((xs, np.sin(xs*freq+phase))).opts(\n",
+    "        responsive=True, min_height=400)\n",
+    "\n",
+    "@pn.depends(freq=freq, phase=phase)\n",
+    "def cosine(freq, phase):\n",
+    "    return hv.Curve((xs, np.cos(xs*freq+phase))).opts(\n",
+    "        responsive=True, min_height=400)\n",
+    "\n",
+    "material.sidebar.append(freq)\n",
+    "material.sidebar.append(phase)\n",
+    "\n",
+    "material.main.append(\n",
+    "    pn.Row(\n",
+    "        pn.Card(hv.DynamicMap(sine), title='Sine'),\n",
+    "        pn.Card(hv.DynamicMap(cosine), title='Cosine')\n",
+    "    )\n",
+    ")\n",
+    "material.servable();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<h3><b>MaterialTemplate with DefaultTheme</b></h3>\n",
+    "<img src=\"../../assets/Material.png\" style=\"margin-left: auto; margin-right: auto; display: block;\"></img>\n",
+    "</br>    \n",
+    "<h3><b>MaterialTemplate with DarkTheme</b></h3>\n",
+    "<img src=\"../../assets/MaterialDark.png\" style=\"margin-left: auto; margin-right: auto; display: block;\"></img>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The app can be displayed within the notebook by using `.servable()`, or rendered in another tab by replacing it with `.show()`. \n",
+    "\n",
+    "Themes can be added using the optional keyword argument `theme`. Each template comes with a DarkTheme and a DefaultTheme, which can be set `MaterialTemplate(theme=DarkTheme)`. If no theme is set, then DefaultTheme will be applied.\n",
+    "\n",
+    "It should be noted that Templates may not render correctly in a notebook, and for the best performance they should ideally be deployed to a server."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}