32  The static app framework

Important

This chapter is being rewritten to utilize Github Codespaces as the primary development platform, which is a recent change. Please bring to my attention anything that doesn’t make sense.

32.1 Goals for this lesson

We will learn the features of this project rig in steps:

  • Templates
    • We’ll learn about static-site generators and templates.
    • We’ll build a new page using the base template.
  • Loops and Google Sheets data
    • We’ll learn about using Google Sheets to manage data in our project.
    • We’ll introduce loops to process data on our pages.
  • Google Docs, ArchieML and baking pages
    • We’ll learn about using Google Docs/ArchieML for content.
    • We’ll learn about the bake command in the project.
    • We’ll create blog pages based on a Google Doc source.
    • We’ll update our index page to build links to the blog pages.

32.2 Set up development environment

Codespaces

We’ll be using Github codespaces for development. If you want to run this locally on your machine, see the README in the template repo.

32.3 Repo from a template

Like our previous two projects, you will start by copying a Github repo and then using a Codespace from your new repo.

  1. Go to github.com/utdata/icj-project-rig.

  2. Click on the green Use this template button and choose Create a new repository.

    • This should allow you to create new repo based on icj-bootstrap-template. Call this new repo yourname-staticapp.
    • Leave all the other settings the same and click Create repository.
    • It takes several seconds to create your repo.

  3. Click on the green <> Code button and then choose the Codespaces tab.

    • Click Create codespace on main.
    • This will take a bit more time, but should just be a couple of minutes. **It will pause at one point and give you a prompt, but wait until you see it say “Detected Node.js” and let it finish that setup.
    • Once the Node installation finishes, your browser will look like you have a version of Visual Studio Code open, and you do!

  4. In the codespace’s VS Code Terminal, run:

    npm install -g gulp

  5. In the Terminal, run gulp dev.

If you get errors, you might have to try npm install and then run gulp dev again.

32.3.1 Some additional setup

Now that we have a codespace running, there are a couple of settings that we need to update to help us later.

  1. In the VS Code icon menus along the left edge, there is a puzzle piece icon to help us intstall extenstions. Click on that icon.
  2. In the search box, type in Nunjucks and look for the extension by “ronnidc”
  3. Click on the Install button to add it to your instance.

Next we need to adjust our settings to understand how to read Nunjucks files.

  1. At the bottom of the VS Code icon bar is a gear. Click on that and gear and go to Settings
  2. Search for “Emmet include” and this should filter the results to Emmet: Include languages.
  3. Click on the Add Item button.
    • For Item, put: njk
    • For Value, put: html
  4. Click on Add Item again
    • For Item, put: nunjucks
    • For Value, put: html

In the end, it should look like this:

Emmet for Nunjucks

Lastly, we want to save your settings profile to Github so you don’t have to do this everytime you create a new Codespace.

  1. In the VS Code icon menu, not quite at the bottom, is the icon for a user.
  2. Click on that “person” icon and then choose Back up and Sync Settings.
  3. Follow the prompts to Sign in using your Github account. (This might force your codespace to restart.)

32.4 Review the example site

Before we talk about how the project architecture is structured, let’s tour the example pages that are included. As we do so, we’ll just touch on how the example code applies to specific project features.

Sample index

Sample detail
  • All the pages on the site have a Bootstrap Navbar and a footer. Each page gets this from a single template, so we don’t have to duplicate code for each new page.
  • The index also has a bookstores list down the page a bit, which is a loop over some data. As we explore the code later you’ll see there is only code for one entry, but we repeat that code for every row in data file. In this case the data was downloaded from a Google Sheets spreadsheet, an optional feature of the project. Sometimes having a structured data source like a spreadsheet is helpful.
  • The index also has a listing of three books. This is also built within a “loop” that allows us to repeat the same code over and over. In this case our book data was downloaded from a Google Docs file written in a special structure called ArchieML, developed by The New York Times.
  • Lastly, there are individual pages for each book listed, which serve as an example of detail pages built from the same template. Only the text and image content is different for each page, but the structure for each page comes from the same template.
  • These specific book pages were created using another feature of the project where we can “bake” pages from data. Instead of a human creating a new file for each library book, they were generated automagically based on data from the Google Doc. If there were 100 books in the data, it would’ve built 100 pages.

Storing our content in Google Docs and Sheets might seem overcomplicated at at first, but it allows us to use Google as a content management system of sorts where many people can collaborate on the content and stay our of our code. It’s super powerful, and used by newsrooms like NYT, NPR and The Texas Tribune.

32.5 Understand the project structure

The README.md in the project template has details about how different features work. READ THE README. While the README file is in your project, you might find it easier to read the README online. We will also go over it in class (or through video).