observable-lab.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b95d43b0-cd6e-4bbb-b0c7-df7246e6b0ff",
   "metadata": {},
   "source": [
    "<h1>\"Hello World\" Observable Tutorial</h1>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d220706-49d4-4a77-9a91-f11a5bb00a6f",
   "metadata": {},
   "source": [
    "The Observable Framework is a powerful tool we will be using to form the backbone of our dashboards. There is no need to reinvent the wheel so we will use Observable Framework to help us build dashboards without getting into the nitty-gritty of programming every aspect. \n",
    "\n",
    "Remember, 67-336 as a class is meant to teach you **how to use effective data visualizations in information systems as a tool for communication**, not a programming class or data science class.\n",
    "\n",
    "<h4>Follow the given instructions carefully and DO NOT skip steps!</h4>\n",
    "<h3><em>You alone will be responsible if something goes awry due to improperly following the instructions!!!!<em></h3>\n",
    "<h4>Remember to carefully read all material, this content will appear on exams.</h4>\n",
    "<br>\n",
    "    \n",
    "*Challenges 1 through 6 are adapted from the official [\"Getting Started\" tutorial](https://observablehq.com/framework/getting-started) offered by the Observable Framework.*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be225bb3-b5a3-4a62-b3a3-477e4bc0b7e7",
   "metadata": {},
   "source": [
    "<h2>Challenge 1: Getting Started</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e774ed5c-63cb-450b-b59c-c1d66f5d3367",
   "metadata": {},
   "source": [
    "We will be using npm as the package manager for this tutorial. Start by creating a folder in which you would like to work on this lab. Now open a new Terminal window at this folder and run the following command in your terminal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "87a4b999-efaa-47bd-8692-6c953729f3c6",
   "metadata": {},
   "outputs": [],
   "source": [
    "npx @observablehq/framework@latest create"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "382673ea-d275-4d9d-808b-0199e23b7848",
   "metadata": {},
   "source": [
    "This command will create an example starter application that we will work on. See the following image to configure the settings for the application. \n",
    ">Use NPM instead of YARN for installing dependencies!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "336e1516-3d48-49a9-b2df-60c35840e865",
   "metadata": {},
   "source": [
    "![Starter Application Configurations in Terminal](https://i.imgur.com/98dnbMz.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08827f20-e0f2-4420-ba13-f965113b932d",
   "metadata": {},
   "source": [
    "In the same terminal, go into the folder where the app is stored by running the following command in the Terminal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43ead920-7d00-4c21-bb06-8e9da3fdeb47",
   "metadata": {},
   "outputs": [],
   "source": [
    "cd hello-framework"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "032a92c1-8a2e-4813-8743-8b966ebdc230",
   "metadata": {},
   "source": [
    "You can now preview the live starter application by running the following command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "58ce2d60-6ff3-4003-8100-5d47eaa2c9c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "npm run dev"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d0c8ed2-b393-41d6-8a9a-17f475ae5e3b",
   "metadata": {},
   "source": [
    "You should see this:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d5b2c40-8e38-4f0f-bdf3-bea14ac5f5bb",
   "metadata": {},
   "source": [
    "![Live Preview of Starter Application in Browser](https://i.imgur.com/e0gEtui.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88a93b04-9103-4e34-ab2d-3380906fc4bb",
   "metadata": {},
   "source": [
    "<h3>Challenge 1.1: Git for Version Control</h3>\n",
    "During the initial creation of the starter application in the Terminal, we already initialized a Git repository **locally** in the configurations.\n",
    "\n",
    "Create a remote Git repository named `observable-lab-67336` in your personal GitHub on GitHub.com.\n",
    "\n",
    "To add this remote repository to your application locally, open a Terminal window at the root folder of your application (`hello-framework`) and use the following command:\n",
    ">`git remote add origin https://github.com/{your-username}/observable-lab-67336.git`\n",
    ">\n",
    ">**Please note that this command will only work if you named the remote repository the name we specified above.**\n",
    ">\n",
    ">Remember to replace {your-username} with your GitHub username! **Do not include the curly brackets.**\n",
    "\n",
    "<h4>Remember to consistently add, commit, and push your changes as you go through this lab.</h4>\n",
    "\n",
    "*We will remind you through this lab, but you should be doing this as good practice for future projects.*\n",
    "\n",
    "When you are ready to push your changes to the remote repository, remember to set the upstream branch your local main branch will track. You can do this by using the following command (**MAKE SURE YOU ARE ON MAIN BRANCH BEFORE RUNNING THIS**):\n",
    ">`git push --set-upstream origin main`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2910e61a-2836-4c59-b310-a738faa7ac7d",
   "metadata": {},
   "source": [
    "<h2>Challenge 2: Creating a Simple Weather Page</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "836de378-f86d-437d-9e37-21acbde3c61c",
   "metadata": {},
   "source": [
    "Notice that there are pages on the sidebar of the starter application. How do we go about adding pages? Pages in Observable are Markdown files (.md) in the folder `src`. Markdown is a lightweight markup language, similar to HTML, that makes it easy to define how documents are written and styled. Here's the link to the cheatsheet for Markdown syntax: https://www.markdownguide.org/cheat-sheet/"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4bee486b-9268-48ac-b2e4-611a8150ba56",
   "metadata": {},
   "source": [
    "Let's practice making a page in Observable. To do this, just create a new Markdown file in the `src` folder with the following commands in your Terminal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "989bc997-bac1-4f7d-ad9c-483ce9f4245c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# goes into the src folder\n",
    "cd src\n",
    "# creates a Markdown file called \"weather\", \"touch\" is the command used to make a new file in Terminal\n",
    "touch weather.md"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2bc39ca-2609-40b4-9411-50b376f4df8e",
   "metadata": {},
   "source": [
    "Now if you refresh your live preview in the browser, you should see a new blank page named \"weather\" in the sidebar that you can click on."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c19e66a7-6c6a-4fe5-ba2c-27465c46d873",
   "metadata": {},
   "source": [
    "Let's add some elements to our new `weather` page. In `weather.md`, add a header to the page using Markdown syntax:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3b2d2e79-654e-475c-a6d0-1d5a0ff182dd",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Weather report"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32198a0a-f67a-4f1a-9e0a-b8dad8169058",
   "metadata": {},
   "source": [
    "The header becomes the title of the page in the sidebar!\n",
    "\n",
    "Now let's add a simple JavaScript element to the page. \n",
    "\n",
    "In order to use Javascript within a Markdown file like `weather.md`, we need to use triple back-ticks `\"```js {code}```\"` to denote a JavaScript code block. The block must be wrapped by triple ticks at the start and end. We use the built in `display()` function to show the output of 1+2 in the example code below. Copy and paste this code block below the header in `weather.md`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed45d5e4-48fe-406f-943e-184902295108",
   "metadata": {},
   "outputs": [],
   "source": [
    "```js\n",
    "display(1 + 2);\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eb14e0c8-90e1-43dd-9522-e7645a8effd2",
   "metadata": {},
   "source": [
    "You should see this:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40fe88d2-86e2-46ff-b491-6e09bbc217c2",
   "metadata": {},
   "source": [
    "![Weather page with header and JS output](https://observablehq.com/framework/_file/getting-started/hello-weather.1c101f09.webp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d822f612-5d7b-47e1-a715-05baa38cb023",
   "metadata": {},
   "source": [
    "The `display()` function is similar to `console.log()` from vanilla JS, but it displays the specified value instead of logging it to console. It is called implicitly when there is an expression like 1+2, displaying 3. You can read more on the function here: https://observablehq.com/framework/javascript#explicit-display.\n",
    "\n",
    "<h3>***Git checkpoint! Did you commit this change yet?***</h3>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e10a06c-ffc2-4c92-bf25-299c4970b759",
   "metadata": {},
   "source": [
    "<h2>Challenge 3: Creating a Data Loader for Forecast API Data</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1d3fc1b-01de-4766-9496-d90363ec13c5",
   "metadata": {},
   "source": [
    "You may be wondering, how can we get and load the data for the visualizations on these pages? Observable uses **data loaders**, which generates static \"snapshots\" of data when the application is built. This optimizes the performance of dashboards built with Observable since it speeds up the display of data. For example, when using data from an external API, the application will take a \"snapshot\" of the data fetched from the external API and use this for computations until it is refreshed (we can control the rate of refresh). This allows for faster computations and use of the data since it has been saved as a static \"snapshot\" and will not need to call the API every time we need to use the data. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3748da0d-f07e-4dbc-82f7-8dbefcb25f20",
   "metadata": {},
   "source": [
    "Let's practice making a data loader in Observable to load some forecast weather data from an external API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9131204-6527-4592-9ce8-4adda410a06a",
   "metadata": {},
   "source": [
    "Start by creating a new file in the `data` folder inside the `src` folder (`src/data`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "736f2d04-8901-4ee8-a826-d9a8209909f1",
   "metadata": {},
   "outputs": [],
   "source": [
    "touch forecast.json.js"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10a557c4-5437-45d5-b3ee-ad1a0b5fdfc2",
   "metadata": {},
   "source": [
    "Observe how the first extension (`.json`) represents the expected return type of the data loader and the second extension (`.js`) represents the language the data loader is written in."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7dd7953c-b686-4fb0-9841-959bee61fa15",
   "metadata": {},
   "source": [
    "We will be using the external API provided by the National Weather Service for this demo. You can read more on the documentation here: https://www.weather.gov/documentation/services-web-api. The endpoint we are using is `GET points/{point}`, where `{point}` is `latitude, longitude`. We've given you a sample point below, which are the approximate coordinates for Hamburg Hall at CMU. Copy and paste them into your data loader file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "70128f66-825a-4fe8-9ba8-b1673456dea2",
   "metadata": {},
   "outputs": [],
   "source": [
    "const longitude = -79.95;\n",
    "const latitude = 40.44;"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfe1fe94-9622-4bcb-b86d-f7387228a628",
   "metadata": {},
   "source": [
    "Now we will write the asynchronous function for fetching/getting the data from the API endpoint (this is a generalized function that can be called with any API endpoint!):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e8b58d22-eb11-4a4b-b612-d241d761d632",
   "metadata": {},
   "outputs": [],
   "source": [
    "async function json(url) {\n",
    "  // The response Object will fulfill the Promise\n",
    "  const response = await fetch(url);\n",
    "\n",
    "  // If the response is not the expected json, it will throw an error that tells us the error code (404, 504, etc.)\n",
    "  if (!response.ok) throw new Error(`fetch failed: ${response.status}`);\n",
    "\n",
    "  // Returns the JSON if the response was the expected response.\n",
    "  return await response.json();\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1aa78398-41b4-4f7e-903a-9bfc2cf16261",
   "metadata": {},
   "source": [
    "Copy and paste the above code into your data loader after the longitude and latitude variables. Now we should call the external API with the function we wrote to fetch the data. Copy and paste the code below after the `json()` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b1220075-741a-4822-af0b-fbe0fee17e73",
   "metadata": {},
   "outputs": [],
   "source": [
    "// gets all the information for the station closest to the given \"Point\" (latitude,longitude)\n",
    "const station = await json(`https://api.weather.gov/points/${latitude},${longitude}`);\n",
    "\n",
    "// gets the specific forecast information (ignoring the excess information about the station we don't need)\n",
    "const forecast = await json(station.properties.forecastHourly);\n",
    "\n",
    "// converts the output into a JSON string (using JSON.stringify()) and prints it to the console (process.stdout.write())\n",
    "process.stdout.write(JSON.stringify(forecast));"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1506fcb4-3615-40b5-9d5e-4557a5ec11a4",
   "metadata": {},
   "source": [
    "Try loading the data in the Terminal with the following command (this is similar to the `CURL` command):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4c3a68a-fea6-4d8d-ad65-5f6efef4c720",
   "metadata": {},
   "outputs": [],
   "source": [
    "node src/data/forecast.json.js"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f5f8d5a3-6b84-4e76-91f9-281323d4c978",
   "metadata": {},
   "source": [
    "You should see the raw JSON output (don't worry, it shouldn't look pretty yet!)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5736901a-3e95-40a8-bf0d-ea99cc1ceb5d",
   "metadata": {},
   "source": [
    "Now that we have our data loader writen, we need to be able to retrieve its output for use. To do this, we can use Observable's built-in `FileAttachment`. This enables us to load the data loader file's output to a variable.\n",
    "\n",
    "See the example below on how we can create a variable to store the data loader output from `forecast.json.js` inside a JavaScript code block using `FileAttachment`. Copy and paste this code into your `weather.md` file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4728056-6e71-46b3-b9e6-250d69487865",
   "metadata": {},
   "outputs": [],
   "source": [
    "```js\n",
    "// creates a variable called forecast that stores the \n",
    "const forecast = FileAttachment(\"./data/forecast.json\").json();\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c1a0f7c-19af-4a1f-ac2a-f4b414e674dc",
   "metadata": {},
   "source": [
    "You can now reference the forecast variable throughout `weather.md` in other code blocks.\n",
    "\n",
    "Delete the code block that displays the output of 1+2 and display \"forecast\" on the `weather` page instead after the code block that declares the \"forecast\" variable (hint: you can use the same `display()` function!)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48e6def2-ebf4-48f0-a5e1-43b42dd45ac7",
   "metadata": {},
   "source": [
    "You should now see the output on your page like this:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f705b0f-ef07-4146-804c-06aaa35f8bbd",
   "metadata": {},
   "source": [
    "![forecast variable output on weather.md](https://i.imgur.com/Y2mwaER.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b4ecba5-43a7-468a-ac07-c7bb32da2c06",
   "metadata": {},
   "source": [
    "If your output doesn't look like this, double check that your code matches the code below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ef5e27a0-6a56-4390-bf67-43094306568b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Weather Report\n",
    "\n",
    "```js\n",
    "const forecast = FileAttachment(\"./data/forecast.json\").json();\n",
    "```\n",
    "\n",
    "```js\n",
    "display(forecast);\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4104a82-a524-49a4-a0e6-012f55afe5f0",
   "metadata": {},
   "source": [
    "<h3>***Git checkpoint! Did you commit this change yet?***</h3>\n",
    "<h2>Challenge 4: Creating a Simple Visualization for Hourly Temperature Forecast</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8eaed02b-ecf1-4f89-b9a3-ed8bd6e445b5",
   "metadata": {},
   "source": [
    "Let's now move on to making a simple visualization in Observable. We will be using the built in `Observable Plot` library for this demo, which is available as `Plot` by default in Markdown. It is the sister library to `D3.js`, which we will be exploring in later projects and labs for this class."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "51c78d35-577c-4db8-92bc-024889be5082",
   "metadata": {},
   "source": [
    "We will be placing the visualization inside `display()` in a JS code block. Delete the `display(forecast);` and write a blank `display();` inside the code block."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2af8bfe-6bcc-4ad7-92f4-4f7d3a7f5852",
   "metadata": {},
   "source": [
    "Now, within the `display()`, we will begin create a simple chart to visualize the hourly temperature forecast from the forecast data we previously retrieved from the API that we have stored in the variable `forecast`. To display the chart, call `Plot` with `Plot.plot({})`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73216f01-bfe7-484b-8dec-f83dd0b05253",
   "metadata": {},
   "outputs": [],
   "source": [
    "```js\n",
    "display(\n",
    "  Plot.plot()\n",
    ");\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "066c9ea2-89f2-4ec9-8318-40c644134f88",
   "metadata": {},
   "source": [
    "Continue by replacing the blank `Plot.plot()` with the following code chunk:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3453421d-054e-477e-a5df-8fa01c0a2a6e",
   "metadata": {},
   "outputs": [],
   "source": [
    "Plot.plot({\n",
    "title: \"Hourly temperature forecast\",\n",
    "x: {type: \"utc\", ticks: \"day\", label: null},\n",
    "y: {grid: true, inset: 10, label: \"Degrees (F)\"},\n",
    "marks: [\n",
    "  Plot.lineY(forecast.properties.periods, {\n",
    "    x: \"startTime\",\n",
    "    y: \"temperature\",\n",
    "    z: null, // varying color, not series\n",
    "    stroke: \"temperature\",\n",
    "    curve: \"step-after\"\n",
    "  })\n",
    "]\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0729a96-1774-4c21-9b6a-501949a91526",
   "metadata": {},
   "source": [
    "Check that your code block now looks like this: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d1cb2b7b-c370-4f39-9c7b-c8e27183df4a",
   "metadata": {},
   "outputs": [],
   "source": [
    "```js\n",
    "display(\n",
    "  Plot.plot({\n",
    "    title: \"Hourly temperature forecast\",\n",
    "    x: {type: \"utc\", ticks: \"day\", label: null},\n",
    "    y: {grid: true, inset: 10, label: \"Degrees (F)\"},\n",
    "    marks: [\n",
    "      Plot.lineY(forecast.properties.periods, {\n",
    "        x: \"startTime\",\n",
    "        y: \"temperature\",\n",
    "        z: null, // varying color, not series\n",
    "        stroke: \"temperature\",\n",
    "        curve: \"step-after\"\n",
    "      })\n",
    "    ]\n",
    "  })\n",
    ");\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aac4efff-7709-480e-985d-4f67ced0e2a4",
   "metadata": {},
   "source": [
    "In your live preview of the application, your `weather` page should look like this:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "858ecc8c-8278-490c-83bd-ae949a5c3ca9",
   "metadata": {},
   "source": [
    "![weather.md with header and simple chart](https://observablehq.com/framework/_file/getting-started/hello-plot.ea32cee1.webp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "860fc46f-976f-4045-a951-a0b42a917f31",
   "metadata": {},
   "source": [
    "Although we do not have time to delve into each portion of how we plotted the chart, feel free to read into the documentation for the library here: https://observablehq.com/plot/ if you're curious about the syntax and how it works.\n",
    "\n",
    "Similar to the `display(1+2)` where `1+2` was the expression and so had the output, `3`, displayed implicitly, our new code block with the chart contains an expression (a call to `Plot.plot`) and so display is also called implicitly. Since this expression evaluates to a DOM element (a `<figure>` containing an `<svg>`), display inserts the element directly into the page. We didn’t have to touch the DOM directly!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77d0e773-b34a-4eb1-989a-b90edb0ba60b",
   "metadata": {},
   "source": [
    "Let's take a small detour back to the data loader, `forecast.json.js`. Edit the longitude and latitude variables in `forecast.json.js` to a different location to see the forecast at the White House (remember to save your changes!):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d6c9734-69df-4099-a61f-5f96fe64f4be",
   "metadata": {},
   "outputs": [],
   "source": [
    "const longitude = -77.04;\n",
    "const latitude = 38.90;"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f3f63708-0e93-40f9-8f61-3c7b4e42864d",
   "metadata": {},
   "source": [
    "Notice how after you save, the Observable framework runs the data loader again and updates the chart accordingly with the new data!\n",
    "<h3>***Git checkpoint! Did you commit this change yet?***</h3>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc259a27-f760-4cbf-8113-29e534c8a1ec",
   "metadata": {},
   "source": [
    "<h2>Challenge 5: Modularizing with Components</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ad7f7799-5016-4153-9745-630897eab917",
   "metadata": {},
   "source": [
    "As pages grow, complex inline JavaScript may become *unwieldy* and *repetitive*. \n",
    "\n",
    "It is best practice to *tidy* code by moving it into functions and thus **modularizing** it. \n",
    "\n",
    "In Observable, a function that returns a DOM element is called a **component**. \n",
    "\n",
    "By placing code into components, we can **reuse** these components in various places in a *readable* and *clean* way."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfce5fa0-28aa-4268-8f1b-252b2bd462a6",
   "metadata": {},
   "source": [
    "To turn the chart we made in Challenge 4 into a component, wrap it in a function and promote the data to a required argument (after all, we cannot plot a chart with no data given!). We will accept an argument called `width`as an optional second argument with for the purposes of styling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "63389411-e4be-4299-95c7-9842d16ed77f",
   "metadata": {},
   "outputs": [],
   "source": [
    "```js\n",
    "function temperaturePlot(data, {width} = {}) {\n",
    "  return Plot.plot({\n",
    "    title: \"Hourly temperature forecast\",\n",
    "    width,\n",
    "    x: {type: \"utc\", ticks: \"day\", label: null},\n",
    "    y: {grid: true, inset: 10, label: \"Degrees (F)\"},\n",
    "    marks: [\n",
    "      Plot.lineY(data.properties.periods, {\n",
    "        x: \"startTime\",\n",
    "        y: \"temperature\",\n",
    "        z: null, // varying color, not series\n",
    "        stroke: \"temperature\",\n",
    "        curve: \"step-after\"\n",
    "      })\n",
    "    ]\n",
    "  });\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec955fef-b9f3-4de8-aa9a-0f46974d957b",
   "metadata": {},
   "source": [
    "We can now just call `temperaturePlot` from anywhere in `weather.md` in a `display()` to cleanly and easily plot the chart:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "239514a3-5120-4337-814c-0a12b7b662c6",
   "metadata": {},
   "outputs": [],
   "source": [
    "```js\n",
    "display(temperaturePlot(forecast));\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8df71189-4db1-4b75-b470-235e63d988d0",
   "metadata": {},
   "source": [
    "We can also place the function into a separate `.js` file to create a standalone module that can be imported into our pages (`.md` files) to *share* the code across pages, write unit tests, and more! This is ideal for **reusability** and **modularity**, particularly for frequently used components and larger components. \n",
    "\n",
    "For this lab, we will not require you to do this but it is good to keep in mind for future larger projects. If you'd like to see an example of this in practice, check out the `timeline.js` file in the `components` folder (`src/components`). It is imported in `example-report.md` at `line 20` and used in `line 28`!\n",
    "\n",
    "<h3>***Git checkpoint! Did you commit this change yet?***</h3>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1dadc5ab-3c4c-4c12-96b1-da284794e9e6",
   "metadata": {},
   "source": [
    "<h2>Challenge 6: Layouts and Styling in Observable</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf17ae00-a05d-47d4-a527-46bc332feff4",
   "metadata": {},
   "source": [
    "We will now briefly touch on layouts and styling in Observable. Usually dashboards have multiple elements and these should be neatly laid out (although we currently only have one chart to lay out). Observable Framework provides us with some simple `grid` and `card` classes that allow for 1 to 4 columns. See the `HTML` code below for an example of how we can do a two-column grid with three cards:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b471cab-6bd2-4c0b-a306-025a094dd381",
   "metadata": {},
   "outputs": [],
   "source": [
    "<div class=\"grid grid-cols-2\">\n",
    "  <div class=\"card grid-colspan-2\">one–two</div>\n",
    "  <div class=\"card\">three</div>\n",
    "  <div class=\"card\">four</div>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa404b4a-fb61-43c7-8e08-3d5c3f2ecb2e",
   "metadata": {},
   "source": [
    "This would look like this when rendered:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c6a96a2-6cf1-48c9-8338-d08db3c1df2f",
   "metadata": {},
   "source": [
    "![layout of two-column grid with three cards](https://i.imgur.com/ifLnEQW.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ce49035-0bac-4ec2-a816-4a4bc06be4bb",
   "metadata": {},
   "source": [
    "Here's something cool: Observable Framework’s grid is actually responsive! On narrow windows, the two-column grid will automatically collapse to a one-column grid. \n",
    "\n",
    "Also of note: Cells in a grid have the same height by default (using `grid-auto-rows`), so consider separate `<div class=\"grid\">` containers if you want to vary row height."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18b08665-e8c2-41f7-8a89-b684da2e325f",
   "metadata": {},
   "source": [
    "When placing charts in a grid, you typically want to render responsively based on the `width` (and sometimes `height`) of the containing cell. \n",
    "\n",
    "Framework’s resize helper takes a `render` function returning a DOM element and re-renders whenever the container resizes.\n",
    "\n",
    "Let's apply all of this to place the chart we made (calling it as a component) into a responsive grid layout:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e6c91e0-01f0-4d19-b1f7-3a0d608fcc8c",
   "metadata": {},
   "outputs": [],
   "source": [
    "<div class=\"grid grid-cols-1\">\n",
    "  <div class=\"card\">${resize((width) => temperaturePlot(forecast, {width}))}</div>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6772a179-6a8a-4edf-b32c-e2a71a3c7c43",
   "metadata": {},
   "source": [
    "It will look like this:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "345a7679-6af2-45c8-8c95-ff81f3252403",
   "metadata": {},
   "source": [
    "![layout of two-column grid with three cards](https://i.imgur.com/4jqI3xR.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32592e04-10c1-4e51-a3a7-90f80041c634",
   "metadata": {},
   "source": [
    "Continuing with styling, Observable Framework provides us with several built-in themes that affect the visual appearance of pages by specifying colors and fonts or augmenting default styles. You can read more about themes in Observable here: https://observablehq.com/framework/themes. We will apply the `dashboard` theme to the `weather` page and disable a table of contents (`toc`) by placing the following code at the very top of the file before anything else:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aba6e47d-92a3-4c0e-8f3d-643c14086404",
   "metadata": {},
   "outputs": [],
   "source": [
    "---\n",
    "theme: dashboard\n",
    "toc: false\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87c13a5f-1010-44a0-8b73-a63f8e2455c4",
   "metadata": {},
   "source": [
    "The `dashboard` theme allows the main column to span the full width of the window; without it, the main column width is limited to 1152px as appropriate for documentation or a report.\n",
    "\n",
    "You should now have something like this, a rudimentary weather dashboard!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01984d7a-8db7-46a0-b617-fa9c343b1ff7",
   "metadata": {},
   "source": [
    "![layout of two-column grid with three cards](https://observablehq.com/framework/_file/getting-started/hello-grid.0d5e9088.webp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89b270b7-4c8b-4a9a-b0d8-ff9ca3d29c4b",
   "metadata": {},
   "source": [
    "<h3>***Git checkpoint! Did you commit this change yet?***</h3>\n",
    "<h2>Challenge 7: Deploying Your Dashboard</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d4e7b4b-ab39-46fb-90b9-739a0c82ae00",
   "metadata": {},
   "source": [
    "This is a reminder to follow the given instructions carefully and do not skip steps. **This is key to not messing up deployment!**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96a89fe4-2524-4f58-ab35-bebd77d291af",
   "metadata": {},
   "source": [
    "<h3>Challenge 7.1: Setting Local Configurations</h3>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3680a736-152b-4ac3-b46f-c43a0f166887",
   "metadata": {},
   "source": [
    "<h4>It is absolutely crucial that you do every single step outlined here.</h4>\n",
    "\n",
    "There are a couple of configurations we will need to set ***PRIOR*** to any sort of deployment.\n",
    "\n",
    "1. Go to `package.json`\n",
    "> Under `\"scripts\"`, change the setting for `\"deploy\"` from `\"observable deploy\"` to `\"vercel --prod\"`.\n",
    "> \n",
    "> The setting should now look like `\"deploy\": \"vercel --prod\",`\n",
    ">\n",
    "> This will allow us to just run `npm run deploy` in the Terminal to deploy to production once we have deployment set up.\n",
    "\n",
    "2. Go to `observablehq.config.js`\n",
    "> There is a commented-out setting called `cleanUrls` (it should be line 36 -> `//cleanUrls: true, // drop .html from URLs`)\n",
    "> \n",
    "> Uncomment this setting by deleting the `\\\\` at the very front of the line (only the first `\\\\`).\n",
    "> Change `true` to `false`.\n",
    ">\n",
    "> The setting should now look like `cleanUrls: false, // drop .html from URLs`\n",
    "> \n",
    "> By default, Observable Framework generates “clean” URLs by dropping the `.html` extension from page links. The webhost we will use for deployment, Vercel, does not support \"clean\" URLs so we are setting that configuration to false.\n",
    "\n",
    "<h3>***Git checkpoint! Did you commit this change yet?***</h3>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a16bbb57-2949-40ac-950f-520978eff29b",
   "metadata": {},
   "source": [
    "<h3>Challenge 7.2: Deployment</h3>\n",
    "1. Start by going to https://vercel.com.\n",
    "\n",
    "   > a. Click **Sign Up** at the top right corner and when prompted, select the Plan Type of *\"I'm working on personal projects. (Hobby tier)\"*\n",
    "   > \n",
    "   > b. Sign up with your **GitHub** account\n",
    "2. Now go back to your application. Open a new Terminal window at the folder where your application is (at the `hello-framework` level). All following commands from this step forward should be run in this Terminal window. **Make sure you are running these commands within the application's folder!**\n",
    ">Run `cd hello-framework` if needed.\n",
    "\n",
    "3. Run the following command in the Terminal:\n",
    ">`npm install -g vercel`\n",
    ">\n",
    ">This will install the Vercel CLI (Command Line Interface).\n",
    "\n",
    "4. Log into Vercel with the account you already registered for in Step 1 by running the following command in the Terminal:\n",
    ">`vercel login`\n",
    ">\n",
    "> When prompted, select **\"Continue with GitHub\"**.\n",
    ">\n",
    ">(use the up and down arrow keys to select, then click the Return key to enter)\n",
    "\n",
    "5. Initialize Vercel within your application by running the following command in the Terminal:\n",
    ">`vercel`\n",
    "> When prompted, reply Yes (just by hitting the Return key) to all prompts.\n",
    "\n",
    "6. Deploy the application to Production by running the following command in the Terminal:\n",
    ">`npm run deploy`\n",
    "\n",
    "8. Each time you make a change, just be sure to run the following commands (in the order given) in the Terminal:\n",
    ">`npm run build`\n",
    ">\n",
    ">`npm run deploy`\n",
    "\n",
    "to re-deploy your changes to production! Your application should also automatically be deployed every time you push a change to main."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29e61dd2-c789-4ba2-a2f2-14c5bf1d6361",
   "metadata": {},
   "source": [
    "<h3>Congratulations on making and deploying your FIRST live dashboard!</h3>\n",
    "<h4>You have now built the equivalent of a \"Hello World\" in Observable!</h4>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}