Russell Gordon

Setting an App Icon

2020-09-20T15:10:00.000Z

An application icon must be provided in many different sizes.

Creating these manually is a tedious task. Fortunately, an application exists to solve this particular problem for app developers. Download Icon Set Creator now.

Open Icon Set Creator once it is downloaded. The first time it runs, you will be prompted to consider financially supporting the developer. If you end up using this app often, I encourage you to do so. For now, click No, Thanks.

Next you may see a dialog mentioning a more capable application that the developer also makes for solving the same problem. That app is more than is necessary for now, so you can dismiss the dialog by pressing No thanks.

You need an image that is at least 1024 pixels wide by 1024 pixels high.

This will typically be a custom-designed icon if you release your app on the public App Store. For your own purposes, any image will do.

I have a nice image of my dog here, but when I open it in Preview, you can see it is not the right size (square).

I'll get a square selection in the image by holding the Shift key down on the keyboard as I move my fingers along the trackpad. To crop the image, I'll use the keyboard shortcut Command-K. Finally, I'll save the image using Command-S.

NOTE: To switch between applications quickly, you can use the keyboard shortcut Command-Tab.

Next, the image must be dragged into Icon Set Creator. Then press the Go button. You can save the output on your Desktop. A folder named iOS will be created. Open this folder, then drag the AppIcon.appiconset folder to the assets folder in Xcode.

The existing placeholder for the app icon is named AppIcon. We can delete this.

Then, we can rename the new app icon we just dragged in, from AppIcon-1 to AppIcon.

That's it! When you next launch the application on a device, you will see that it has an icon!

Keyboard Shortcuts in Playgrounds

2021-09-19T15:51:00.000Z

Keyboard shortcuts let us reduce the amount of time we spend reaching for the trackpad or a mouse.

Learn the shortcuts below and gain one of the small but helpful "super powers" of experienced software developers.

Run Playground

Run the latest version of your code.

Shortcut: Command-R

Step Through My Code

Step through your code, showing what line is being run, one at a time, when the playground runs.

Shortcut: Shift-Command-R

Toggle the visibility of the navigation sidebar. Hiding the sidebar provides more space to view your code!

Shortcut: Option-Command-S

Increase Text Size

Increase the size of text in the code window.

Shortcut: Command + or Command =

Decrease Text Size

Decrease the size of text in the code window.

Shortcut: Command -

Select All Text

Select all the text in the code window.

Shortcut: Command-A

Re-Indent

For any code that is selected, it will be re-indented.

This is a great way to clean up your code to make it more readable!

It can also be a way to spot syntax errors, when opening or closing curly brackets for a code block are missing.

Shortcut: Control-I

Shift Right

For the line of code the cursor is on, or for a selected block of code, shift the code to the right.

Shortcut: Command-]

Shift Left

For the line of code the cursor is on, or for a selected block of text, shift the code to the left.

Shortcut: Command-[

Move to End of Current Line

Move the cursor to the end of the current line.

Shortcut: Command-→

Move to Start of Current Line

Move the cursor to the start of the current line.

Shortcut: Command-←

Select Entire Line

Select an entire line of code, either above or below the cursor.

Shortcut: Shift-↑ or Shift-↓

Block Comment

Toggle a selected block of code between being commented out or active.

Code that is commented out will not be run by the playground.

Shortcut: Command-/

Ginger Molasses Cookies

2021-04-21T19:10:00.000Z

Preamble

A certain purveyor of coffee in North America sells a ginger molasses cookie that is much loved by my partner and I. After a lot of delicious trial and error, this is our version of that cookie. We daresay it's as good as and possibly better than the original!

Preparation time

2 to 3 hours to let butter soften at room temperature
½ hour to mix wet and dry ingredients
1 ½ hours for dough to cool in refrigerator
1 hour to roll and bake cookies

Yield

Approximately 24 to 28 cookies.

NOTE: Images shown below were taken when recipe was doubled to yield approximately 48 to 56 cookies.

Equipment

2 to 4 cookie pans, 43.8 x 29.2 x 2.54 cm
4 silicon baking sheets, or, parchment paper
large mixing bowl
medium mixing bowl
electric mixer or wooden spoon
2 cooling racks
food scale
whisk
spatula

Ingredients

Dry

295 g all-purpose unbleached white flour
1 tsp. baking soda
1 tsp. cinnamon
2 tsp. ground ginger
½ tsp. salt

Wet

170 g unsalted butter, softened
110 g white sugar
110 g brown sugar
1 egg, room temperature
½ tsp. pure vanilla
60 g molasses

Topping

approximately 250 g coarse dark granulated sugar

Directions

About five hours before you wish to complete the baking process, measure out the butter, and place in the large mixing bowl. Chopping the butter into smaller cubes hastens the softening process.
About 2 to 3 hours later, set the egg out to warm to room temperature.
Beat the butter until it is light and airy.

Using a whisk, combine dry ingredients in the medium mixing bowl.

Combine white sugar with contents of large mixing bowl.

Combine brown sugar with contents of large mixing bowl.

Add egg, vanilla, and molasses to large mixing bowl, then combine.

Gradually add dry ingredients to wet ingredients. Four rounds of combining dry to wet works well. Dough will be stiff.

Dough will become stiff as the mixing continues. When complete the dough is ready to be chilled.

Set the dough in a refrigerator to chill, covered, for 1 and ½ hours.
Pre-heat an oven to 350 °F with convection, or 375 °F without.
For the topping, place the coarse, dark, granulated sugar in a low-rimmed bowl.

Using a small cookie dough scoop (pictured at left in first image) and a butter knife, scoop dough from mixing bowl.

Roll the dough between your hands, then gently compress the ball of dough in the granulated sugar, and place on cookie sheet.

Repeat steps 12 and 13 until you have 8 cookies per baking sheet.
With a convection oven you can bake 16 cookies, one sheet per oven rack. Bake for 15 minutes. While first batch of cookies bakes, prepare the second batch of cookies for baking.

When cookies have baked for 15 minutes, remove from oven and let cool for 3 minutes, then use a spatula to move to a cooling rack. Allow oven to reheat before placing the next batch in the oven.

When cooled, cookies should be moderately crisp at the edges, but soft and chewy at their centre. Enjoy! 😀

Getting to Know Core Data

2021-01-03T18:15:00.000Z

If you've made it to Day 61 of Paul Hudson's 100 Days of SwiftUI tutorial series then you probably have a healthy appreciation for the quality and value of that free resource.

I teach high school computer science in Ontario, Canada. Although our curriculum is excellent student enrolment numbers have never been high enough to warrant interest from textbook publishers. On top of that, any textbook written for a particular programming language or framework would quickly become out of date. So in years past I have often ended up writing all of the material my students work with. Compared to, say, a biology teacher – I write both the textbook and the lesson plans.

So I am especially grateful for Paul's writing. He has a real knack for explaining topics within a context, in simple terms, often with a dash of humour. I am unequivocally in awe of the volume of his output. Both myself and my students have found his tutorials to be enormously helpful.

The core challenge of days 60 and 61 is to build an application that shows user data to illustrate connections between friends. At first, user data pulled from the remote JSON file is stored entirely in-memory. Later we are asked to modify the application so that data is kept inside a Core Data store – in this way, it would not be necessary to load the JSON file from the remote server each time the application opens.

In my experience Paul scaffolded concepts well leading up to this task – he provided prerequisite tasks that build necessary skills:

On days 49 through 52 we built the Cupcake Corner app which involved sending and retrieving JSON to a remote server.
On days 53 through 56 we built Bookworm which involved writing an app to track books a person has read and their rating for each title. Information was stored in a Core Data store.
On days 57 through 59, we built a technique project – essentially a series of small examples of functionality – that methodically illustrated concepts we'd need to employ later on – such as using the NSPredicate class or understanding relationships between entities.

That said, from what I have read on Twitter and in the discussion forums Paul operates to support learners, there is a sense that learning Core Data is hard and that the Day 61 challenge can be especially tricky.

Additionally, changes to how the SwiftUI application lifecycle works as of Xcode 12 – released after Paul wrote these tutorials – provide additional wrinkles.

On that note, the purpose of this post is to share:

solutions to some of the roadblocks I encountered
a few tips to make debugging with Core Data easier
some links to additional resources that were especially helpful

End Product

Here is a brief overview of what my Friends app looked like when it was complete:

I modified the core challenge in the following ways:

used the SwiftUI App life cycle option, rather than UIKit App Delegate
loaded user data at the application level, prior to the appearance of the first view or window
pulled down images of users from Random User Generator service
added a second view so that the app supports the notion of marking friends as belonging to an "inner circle" of close friends
made it possible to use Xcode Previews with a smaller set of user data loaded into an in-memory Core Data store

SwiftUI App Life Cycle and the Provided Template

The first bump in the road came when I chose to create my Friends app using the newer SwiftUI App life cycle option, rather than the UIKit App Delegate option that I'd used when following Paul's tutorials in the lead-up to days 60 and 61.

In theory, Xcode provides templates to get developers moving from common starting points.

Using Xcode 12.3, after creating a new project using the SwiftUI App lifecycle option, and ensuring that the Use Core Data option was enabled, I built and ran the project. Here is what I saw:

Not a promising start – we should see toolbar buttons that allow us to add and remove items from a list.

I found the solution on the Apple Developer Forums. Here is a diff of the changes and here is the entire ContentView.swift file that corrects the issue.

Tip: Enable Core Data Debugging

When programming a user interface in SwiftUI, we get feedback instantly in Xcode Previews.

This makes it really fast to iterate and improve a user interface. It's one of the primary reasons I love working with the SwiftUI framework.

However, my initial experience programming with Core Data left me wondering exactly what was happening behind the scenes on a fairly regular basis.

Did that user record just get added to the Core Data store?

How could I be sure?

I needed a way to debug Core Data operations.

I found this article by Donny Wals and it was super helpful.

For the rest of my time completing the day 61 challenge, I ran my project with this launch argument enabled:

-com.apple.CoreData.SQLDebug 1

That was enough to help me see what was happening with Core Data behind the curtain.

Loading User Data at the Application Level

It seems pretty clear to me that with the days 60 and 61 challenge, Paul intended for learners to parse the JSON and eventually load that information into Core Data using the .onAppear modifier of the first view – we were told as much when setting up the Bookworm app:

All our managed objects live inside a managed object context, which is the thing that’s responsible for actually fetching managed objects, as well as for saving changes and more. You can have many managed object contexts if you want, but that’s quite a way away right now – realistically you’ll be fine with one for a long time yet.

We don’t need to create this managed object context, because Xcode already made one for us. Even better, it already added it to the SwiftUI environment, which is what makes the @FetchRequest property wrapper work – it uses whatever managed object context is available in the environment.

Even when using the newer the SwiftUI App lifecycle, we're in good shape based upon what the Xcode template provides.

In the ProjectNameApp.swift file (where ProjectName is whatever name you selected when creating the project in Xcode), there is this code:

@main
struct FriendsApp: App {
    let persistenceController = PersistenceController.shared

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.managedObjectContext, persistenceController.container.viewContext)
        }
    }
}

The .environment modifier on ContentView injects the managed object context into the environment, so that it is later available to SwiftUI views through the @Environment property wrapper, just like in the earlier tutorials from Paul:

@Environment(\.managedObjectContext) var moc

So what's the problem?

Well, I decided that I didn't want to parse the JSON file and load it into Core Data on the first view my app presents.

This speaks to separation of concerns. I know that it's generally not ideal to closely tie together the parts of your app that store data with the parts of your app that display the data.

I should have just rolled with it. I would have made my life easier. I expect that in a future tutorial, Paul will show learners how to better separate code for handling data from code for handling the user interface.

I didn't roll with it.

If you want to talk to Core Data outside of a SwiftUI view you need to know where to find the managed object context.

In the template Xcode 12 provides, that is via the PersistenceController struct from the Persistence.swift file. A static property provides access to a managed object context that runs on the main thread of an app:

PersistenceController.shared.container.viewContext

My next question was how to best load user data directly into Core Data.

One could decode the JSON into structures that exist in memory, and then load the data in those structures into Core Data objects, but that does not sound terribly memory efficient.

So how could I get the data directly into Core Data from the external JSON file?

I really didn't know how that might be done.

With some looking, I once again found a Donny Wals article that provided an answer.

Decoding JSON Directly into Core Data Objects

Essentially, decoding JSON directly into instances of Core Data classes is pretty much identical to decoding JSON directly into instances of structures or classes that you define yourself. You just need to provide a managed object context for the JSONDecoder class so that it can talk to the Core Data store.

So now, within the shared data task of URLSession, after pulling the JSON data down from Paul's website, I was kicking off parsing the JSON into Core Data with this segment of code:

// Now decode from JSON directly into Core Data managed objects
let decoder = JSONDecoder(context: PersistenceController.shared.container.viewContext)
if let decodedData = try? decoder.decode([CDUser].self, from: unwrappedData) {
	print("There were \(decodedData.count) users placed into Core Data")
} else {
	print("Could not decode from JSON into Core Data")
}

My CDUser+CoreDataClass.swift file looked like this:

//
//  CDUser+CoreDataClass.swift
//  Friends
//
//  Created by Russell Gordon on 2020-12-27.
//
//

import Foundation
import CoreData

@objc(CDUser)
public class CDUser: NSManagedObject, Decodable {

    // What properties to decode
    enum CodingKeys: CodingKey {
        case id
        case isActive
        case name
        case age
        case company
        case email
        case address
        case about
        case registered
        case tags
        case friends
    }

    required convenience public init(from decoder: Decoder) throws {
        
        // Attempt to extract the object
        guard let context = decoder.userInfo[.context] as? NSManagedObjectContext else {
            fatalError("NSManagedObjectContext is missing")
        }
        
        let entity = NSEntityDescription.entity(forEntityName: "CDUser", in: context)!
        
        self.init(entity: entity, insertInto: context)
        
        let container = try decoder.container(keyedBy: CodingKeys.self)
        
        id = try container.decode(String.self, forKey: .id)
        isActive = try container.decode(Bool.self, forKey: .isActive)
        name = try container.decode(String.self, forKey: .name)
        age = try container.decode(Int16.self, forKey: .age)
        company = try container.decode(String.self, forKey: .company)
        email = try container.decode(String.self, forKey: .email)
        address = try container.decode(String.self, forKey: .address)
        let untrimmedAbout = try container.decode(String.self, forKey: .about)
        about = untrimmedAbout.trimmingCharacters(in: CharacterSet(charactersIn: "\r\n"))
        
        // Decode the date
        // SEE: https://developer.apple.com/documentation/foundation/dateformatter#overview
        // SEE: https://developer.apple.com/documentation/foundation/iso8601dateformatter
        // SEE: https://makclass.com/posts/24-a-quick-example-on-iso8601dateformatter-and-sorted-by-function
        let dateAsString = try container.decode(String.self, forKey: .registered)
        let dateFormatter = ISO8601DateFormatter()
        registered = dateFormatter.date(from: dateAsString) ?? Date()

        // Decode all the tags and tie to this entity
        let tagsAsStrings = try container.decode([String].self, forKey: .tags)
        var tags: Set<CDTag> = Set()
        for tag in tagsAsStrings {
            let newTag = CDTag(context: context)
            newTag.name = tag
            // Associate each tag in the set with this user
            newTag.tagOrigin = self
            tags.insert(newTag)
        }
        tag = tags as NSSet
        
        // Decode all the friends and tie to this entity
        let friends = try container.decode(Set<CDFriend>.self, forKey: .friends)
        for friend in friends {
            // Associate each friend in the set with this user
            friend.friendOrigin = self
        }
        friend = friends as NSSet
                
    }
    
}

However... I was now seeing very odd behaviour.

Sometimes, 100 users, as expected, would be loaded from the JSON file into Core Data.

And sometimes, 99 users would be loaded. Or 98.

Or on occasion, the app would just crash. 😕

Tip: Enable Concurrency Debugging

I tend to become laser focused on solving one problem while programming when instead I should take a step back and examine the larger picture. Or... maybe just read resources that I come across more carefully.

Had I read a bit further in the Donny Wals article on using launch arguments for Core Data debugging, I would have found this key paragraph (emphasis and link mine):

One of the biggest frustrations you might have with Core Data is random crashes due to threading problems. You're supposed to use [the] managed object context and managed objects only on the threads that they were created on, and violating this rule might crash your app. However, usually your app won't crash and everything is fine. But then every now and then a random crash pops up. You can tell that it's Core Data related but you might not be sure where the error is coming from exactly.

By enabling this launch argument:

-com.apple.CoreData.ConcurrencyDebug 1

... you are asking iOS to enforce a contract – you promise, as the programmer, to only use a managed object context on the thread it was created on.

If you break that contract, the app will immediately crash (with a rather cute error message of "all that is left to us is honor").

This is a far superior state of affairs to having your app sometimes work and sometimes not.

The problem I had was that I was passing the managed object context for the main thread of my app to JSONDecoder, within a shared data task for URLSession – a task that will be run on a background thread:

URLSession.shared.dataTask(with: request) { data, response, error in
	
	// handle the result here – attempt to unwrap optional data provided by task
	guard let unwrappedData = data else {
		
		// Show the error message
		print("No data in response: \(error?.localizedDescription ?? "Unknown error")")
		
		return
	}
	
	// Now decode from JSON directly into Core Data managed objects
	let decoder = JSONDecoder(context: PersistenceController.shared.container.viewContext)
	if let decodedData = try? decoder.decode([CDUser].self, from: unwrappedData) {
		print("There were \(decodedData.count) users placed into Core Data")
	} else {
		print("Could not decode from JSON into Core Data")
	}
	
	// and so on...

}

That violates the Core Data concurrency contract.

Using Background Threads and Loading User Images

I will save you the tortured play-by-play recounting of my experience at this point.

To summarize, I eventually found this example project provided by Apple that illustrates best practices for loading JSON into Core Data on a background thread.

In the final version of my Friends app, within the initializer of my FriendsApp struct, I kick off loading user data like this, prior to any views being displayed:

// Kick off loading users from JSON or Core Data
_ = DataProvider()

Here is what my DataProvider class looks like.

Notice that each time operations are performed with Core Data, they occur on a background managed object context.

In the fetchAndSaveAvatars() method you will see how user images are loaded.

Again, note that a background managed object context is created within the shared data task on URLSession. This occurs 100 times, since there are 100 users.

It will not work to create a background managed object context outside the shared data task – that breaks the Core Data concurrency contract.

Additional Resources

As I mentioned earlier, I extended the day 61 challenge a bit further by adding the notion of an "inner circle" of friends presented on a second tab.

A badge icon is updated as friends are added to the "inner circle" list. The count of items in the badge is reduced once the user of my app views the friend's details from within the "inner circle" tab.

At present, it seems there is no direct way to add a notification badge to a tab item in SwiftUI – so we have to do it manually, as explained here.

I also found this NSPredicate cheat sheet to be useful.

Finally, I worked out how to continue using Xcode Previews to refine my SwiftUI views while still using Core Data.

You are welcome to download and browse the code of my finished Friends app to see how that was done. Xcode 12.2 or later is recommended to open and build that project.

This article became more lengthy than I intended. 😅

If you've found it useful, or noticed any errors, please let me know!

Creating a New Xcode Project for a SwiftUI App

2020-08-17T15:31:00.000Z

Everyone was a beginner at some point, and this article is for those just starting out.

For pure SwiftUI apps, there are some changes in the app life cycle in Xcode 12 that affect the creation of a new project.

So here is a brief description of how to get started with the most basic form of iOS app using SwiftUI in both recent versions of Xcode.

Xcode 12

From the menu, choose File → New → Project... or use the keyboard shortcut Shift-Command-N.

Now you will choose a project template. In this sheet, select the iOS tab, then App, then press Next:

The following sheet allows you to select various options for the project. It looks like this:

Make the Product Name something concise but descriptive that will allow you to find the project on your computer in the future. Don't worry – the name you choose here does not commit you to using that same name for what end-users will eventually see for your app on their home screen icon and in the App Store.

If you see an Add account... button rather than a pop up menu to select a team, then press the button and follow the steps to either log in with, or create a new, Apple ID. This will be helpful later on – having a team specified for your project will permit you to load your app on to devices for testing purposes.

You can leave the Organization Identifier field with its default value.

Be sure that the Interface field is set to SwiftUI.

The Life Cycle field should be set to SwiftUI App.

The Language field should be set to Swift.

All of the various checkboxes at the bottom of this sheet can be unchecked.

Now, press the Next button.

You will then see a sheet that allows you to select where to save your work. I really recommend being organized about where you save your work on your computer. The sheet looks like this:

Be sure to enable source control, so that a git repository is created, as pictured. More on source control in another post, but basic usage of git is not hard, and there are many benefits.

Then, press the Create button.

That's it! You're ready to start building your SwiftUI-based iOS app in Xcode 12. 🚀

Xcode 11

From the menu, choose File → New → Project... or use the keyboard shortcut Shift-Command-N.

Now you will choose a project template. In this sheet, select the iOS tab, then Single View App, then press Next:

The following sheet allows you to select various options for the project. It looks like this:

You can leave the Organization Name and Organization Identifier fields with their default values.

The Language field should be set to Swift.

Set the User Interface field to SwiftUI.

All of the various checkboxes at the bottom of this sheet can be unchecked.

Now, press the Next button.

You will then see a sheet that allows you to select where to save your work. I really recommend being organized about where you save your work on your computer. The sheet looks like this:

Be sure to enable source control, so that a git repository is created, as pictured. More on source control in another post, but basic usage of git is not hard, and there are many benefits.

Then, press the Create button.

That's it! You're ready to start building your SwiftUI-based iOS app in Xcode 11. 🚀

Creating a Custom Theme Using Publish

2020-08-13T13:30:00.000Z

The Swift community is fortunate to have many knowledgeable and generous members, one of whom is John Sundell, the author of the Publish static site generator.

This very site is generated using Publish.

[!NOTE]
As of March 2024, this site is published using the Obsidian Digital Garden Plugin.

This article will expand on the instructions provided for creating your own theme, and cover:

duplicating the provided Foundation theme as a starting point for creating your own theme
adjusting the presentation of content using CSS
modifying site content using the domain-specific language (DSL) of Plot
enabling Splash and its Swift syntax highlighting plugin

If you prefer video, this tutorial by Kilo Loco is an excellent option.

Getting started

If you are reading this post and wondering how to even begin using Publish to generate a site, I found this post by Perttu Lähteenlahti very helpful.

Let's assume you have followed Perttu's instructions, that you created a site called SomeNewSite, and you are viewing the result generated by Publish:

Duplicating the Foundation Theme

In the SomeNewSite folder, open Package.swift using Xcode.

In Xcode, open Sources → SomeNewSite → main.swift.

The following should catch your eye:

// This will generate your website using the built-in Foundation theme:
try SomeNewSite().publish(withTheme: .foundation)

Command-clicking on the .foundation argument and choosing Jump to Definition reveals that the Theme+Foundation.swift file defines the Foundation theme. Progress!

It is not advisable to modify the provided theme as future updates to Publish will create conflicts with any changes you make.

It is better to duplicate the provided theme. You can then use the duplicate as a starting point for defining the content and presentation of your website.

Before leaving the Theme+Foundation.swift file, highlight and copy all its code to your clipboard: Command-A and then Command-C will do the trick.

Say your new theme will be named Basic. Create a file named Theme+Basic.swift in the Sources → SomeNewSite folder:

Place your cursor in that newly created file and replace the existing code: Command-A then Command-V.

At this point you may wish to update the comment at the top of the Theme+Basic.swift file:

//
//  Theme+Basic.swift
//
//
//  Created by Your Name on 2020-08-13.
//

It is now necessary to import a couple of additional packages.

Above the import Plot statement, add:

import Foundation
import Publish

The Theme extension tells Publish where to find the stylesheet that will control the presentation of content. Make edits so that the Theme extension is defined as follows:

extension Theme where Site == SomeNewSite {
    /// My customized "Basic" theme.
    static var basic: Self {
        Theme(
            htmlFactory: BasicHTMLFactory(),
            resourcePaths: ["Resources/BasicTheme/styles.css"]
        )
    }
}

Next, where the FoundationHTMLFactory struct is defined:

private struct FoundationHTMLFactory<Site: Website>: HTMLFactory {

... make edits such that the code reads as follows, instead:

private struct BasicHTMLFactory: HTMLFactory {

If you now switch to the Terminal application, and type publish run in the SomeNewSite folder, the compiler will throw many errors. For example:

error: reference to invalid associated type 'Site' of type 'BasicHTMLFactory'
    func makeSectionHTML(for section: Section<Site>,
                                              ^

By switching to Xcode, command-clicking on the Site type (line 23, for example), and choosing Jump to Definition, you will see:

public protocol HTMLFactory {
    /// The website that the factory is for. Generic constraints may be
    /// applied to this type to require that a website fulfills certain
    /// requirements in order to use this factory.
    associatedtype Site: Website

    ...
    
}

In main.swift a struct named SomeNewSite that conforms to the protocol Website is defined.

And there is the solution¹ – in Theme+Basic.swift all references to the Site type parameter in the BasicHTMLFactory struct must be replaced with references to the SomeNewSite type.

Do this now in Xcode. Be sure to use a case-sensitive find and replace operation, but be careful not to acccidentially replace the Site text in the extension of the Theme type (probably on or around line 12).

You are almost done! 😅

Return to main.swift. Tell the compiler to build your site using the new theme. Update the final two lines of code to read:

// Generate the website using my customized Basic theme
try SomeNewSite().publish(withTheme: .basic)

Switch to the Terminal application. Type publish run in the SomeNewSite folder. The Swift code will now compile, but the site will not generate, because Publish cannot find the stylesheet:

Fatal error: Error raised at top level: Publish encountered an error:
[step] Generate HTML
[path] Resources/BasicTheme/styles.css
[info] Failed to copy theme resource

To correct this, in your Resources folder, create a new folder named BasicTheme.

Inside that folder, create a new file named styles.css.

Expand the Publish package in Xcode, then navigate to the Resources → FoundationTheme folder.

From the FoundationTheme folder, copy and paste the entire conents of the styles.css file into your newly created CSS file in the BasicTheme folder.

Here is what things should generally look like at this point:

You may now wish to update the comment at the top of your new stylesheet file.

Switch back to the Terminal application. Type publish run in the SomeNewSite folder. This time the site should generate successfully.

If you load the site, you should once again see the following:

It is perhaps a bit deflating to do all that work to get the same result, but now the site is being generated by your own custom theme. It gets easier from here!

Adjusting Presentation Using CSS

Now that the Basic theme is set up, adjusting the presentation of site content using CSS is straightforward.

Test that this is working by adjusting the background color in styles.css inside the BasicTheme folder to display in orange:

body {
    background: orange;
    color: hsl(0,0%,0%);
    font-family: Helvetica, Arial;
    text-align: center;
}

Note that if your computer is running in dark mode, you'd need to change this section of the styles.css file instead:

@media (prefers-color-scheme: dark) {
    body {
        background-color: orange;
    }
    ...
}

Whenever you make an edit to the stylesheet, the website must be rebuilt. In the SomeNewSite folder, type publish run.

Now reload the page in your web browser.

You should see that the background of the page is now bright orange.

Beware: browsers will, whenever possible, load files from a cache rather than from the server. Since you are trying to test a change to your stylesheet, it's important that you are not reloading from a cache of the original stylesheet.

In Safari, Option-Command-R triggers the Reload Page from Origin command, which should ignore any cached files and instead, as suggested by the name, reload files from the server. In Chrome, I believe the equivalent command is Shift-Command-R.

It is helpful to enable the Develop menu in Safari. To do this, open Safari Preferences, and on the Advanced tab, enable the Show Develop menu in menu bar option.

From the Develop menu, Option-Command-E to trigger the Empty Caches command can be useful.

For further reading, if you are new to web development, learning how to inspect web page elements is recommended. This tutorial on CSS selectors may also be helpful.

If you've made a change to a CSS file, but do not see it reflected on your page, do not worry. This happened to me dozens of times. Ask yourself these questions:

Did I save changes to the CSS file?
Did I remember to issue the publish run command to regenerate the website?
Did I reload the page ignoring cached files? (see keyboard shortcuts above)
Have I emptied the browser cache? (see keyboard shortcut above)
Am I using the correct CSS selectors to target an element? (see suggested further reading above)

Modifying Content Using Plot

Plot defines a domain-specific language (DSL) for writing HTML in Publish. This means you can safely write HTML using Swift. It's worth reading the documentation – it is extensive and well written.

Let's review a quick example here. Say that you wish to add the date of a published article to the item list on the main page, so that the page will look like this²:

Open the Theme+Basic.swift file in Xcode, and navigate to the itemList method.

Add a call to the h2 method just below where the h1 method is invoked:

static func itemList<T: Website>(for items: [Item<T>], on site: T) -> Node {
	return .ul(
		.class("item-list"),
		.forEach(items) { item in
			.li(.article(
				.h1(.a(
					.href(item.path),
					.text(item.title)
				)),
				.h2(.text("Published on: \(item.date)")),
				.tagList(for: item, on: site),
				.p(.text(item.description))
			))
		}
	)
}

That new code retrieves the date of the current item and positions it just below a link to the item.

If you regenerate the site using the publish run command, and reload it in your browser, you should see something like this:

The date is not nicely formatted.

The wonderful part of building a website using Swift is that you can apply all your existing knowledge to the endeavour.

Add a quick extension to the Date type at the top of Theme+Basic.swift:

extension Date {
    var asText: String {
        let formatter = DateFormatter()
        formatter.dateFormat = "dd MMMM, yyyy"
        let dateString = formatter.string(from: self)
        return dateString
    }
}

... and a slight change to the itemList method:

.h2(.text("Published on: \(item.date.asText)")),

... and you should find that the date is now better formatted.

I often forget the rules for formatting dates in Swift; this site is a useful reference.

To learn more about how to build site content using the Plot DSL, do have a look at Kilo Loco's video.

To see the complete list of HTML elements that the Plot DSL API supports, this page is helpful.

Remember, Plot is extensible – you can define your own components, and more.

Enabling Splash for Swift Syntax Highlighting

Being able to share nicely highlighted excerpts of Swift code on this website was the motivating factor for my own move to using the Publish static site generator.

To get started, per John Sundell's instructions, modify Package.swift to read as follows:

// swift-tools-version:5.2

import PackageDescription

let package = Package(
    name: "SomeNewSite",
    products: [
        .executable(
            name: "SomeNewSite",
            targets: ["SomeNewSite"]
        )
    ],
    dependencies: [
        .package(name: "Publish", url: "https://github.com/johnsundell/publish.git", from: "0.6.0"),
        .package(name: "SplashPublishPlugin", url: "https://github.com/johnsundell/splashpublishplugin", from: "0.1.0")
    ],
    targets: [
        .target(
            name: "SomeNewSite",
            dependencies: ["Publish", "SplashPublishPlugin"]
        )
    ]
)

Next, changes to main.swift are required.

Add this line to the end of the list of import statements:

import SplashPublishPlugin

Modifications to the final line of code are required. Your site is currently being generated with the default pipeline provided by Publish:

// Generate the website using my customized Basic theme
try SomeNewSite().publish(withTheme: .basic)

To use Splash, a customized pipeline for website generation is required.

Modify the code to read as follows:

try SomeNewSite().publish(using: [
  .copyResources(),
  .installPlugin(.splash(withClassPrefix: "")),
  .addMarkdownFiles(),
  .sortItems(by: \.date, order: .descending),
  .generateHTML(withTheme: .basic),
  .unwrap(RSSFeedConfiguration.default) { config in
      .generateRSSFeed(
        including: [.posts],
          config: config
      )
  },
  .generateSiteMap()
])

That custom publishing pipeline mimics the default pipeline, but includes Splash.

Now, navigate to the Content → posts folder in Xcode.

Modify first-post.md, below the metadata section, to read as follows:

# My first post

My first post's text.

```
var i = 10
while i > 0 {
    print("\(i)...")
    i -= 1
}
print("Blast off!")
```

Now invoke publish run to regenerate your site. From the main page, follow the link to read the post.

You might be disappointed to see that the Swift code is not syntax-highlighted.

Inspect an element near the start of the Swift code block.

You should see something like this:

&lt;span class="keyword"&gt;var&lt;/span&gt;

In other words, what's happening is that Splash wraps Swift code in <span> tags that specify certain CSS classes.

To see color-highlighted code, CSS is required.

Just below is CSS that will provide colors according to John Sundell's theme³. Copy and paste this at the bottom of your styles.css file in the BasicTheme folder⁴:

pre code {
    color: hsl(180,12%,70%);
}

.preprocessing {
    color: hsl(45,100%,36%);
}

.comment {
    color: hsl(195,16%,50%);
}

.number {
    color: hsl(11,65%,60%);
}

.call {
    color: hsl(209,77%,55%);
}

.property {
    color: hsl(174,68%,40%);
}

.keyword {
    color: hsl(331,79%,57%);
}

.dotAccess {
    color: hsl(71,100%,35%);
}

.type {
    color: hsl(241,41%,65%);
}

.string {
    color: hsl(19,96%,55%);
}

Regenerate your site, and reload the post. You should now see that the Swift code is syntax-highlighted with color.

You can customize the colors as desired, of course.

If you are looking to mimic colors from existing themes, I think you will find the Classic Color Meter app to be very useful. I purchased Classic Color Meter and used it extensively while developing this site's look and feel.

The Paletton site is also excellent.

Conclusion

Whew! 😅

I hope this article has helped you blast off with Publish. 🚀

Please let me know how this goes for you.

I'd love to keep this article current, so if something doesn't work for you, please let me know.

Good luck!

This may not be the most correct solution; I welcome suggestions for a better approach.^
I've removed the orange background from the last section of this tutorial.^
On Friday, August 14, 2020, the destination for this link was updated to point to a stylesheet designed specifically for presenting code with Splash, as opposed to linking to an Xcode theme with John Sundell's colors.^
On March 29, 2024, CSS color codes in hexadecimal were converted to their HSL equivalents.^

Core Data and Xcode Previews

2021-07-18T22:30:32.000Z

Right now I am reading through Practical Core Data by Donny Wals.

Reading that book has been a welcome consolidation of my understanding of Core Data.

My first exposure to the Core Data framework was rough, entirely due to my own predisposition to biting off more than I can chew.

When last using Core Data, I was at first disappointed because I did not understand how to provide sample data to views rendered in Xcode Previews. The ability to rapidly iterate design ideas for a view in Xcode Previews is one of my favourite aspects of programming with the SwiftUI framework.

I was delighted when I eventually cobbled together some understanding of how to use Xcode Previews while obtaining sample data through a Core Data store. My intent is to clearly describe how to do just that in this article.

Starting Point

This Xcode project uses a basic Core Data model without support for working with views in Xcode Previews.

It was created using Xcode 12.5.1 – download the project to follow along, and if necessary, that version of Xcode.

The finished project, including the code necessary to drive Xcode Previews, is included at the end of this article.

In the project you will find an app that I built by, for the most part, following the instructions provided in Chapter 1 of Practical Core Data.

The app is very basic, allowing a user to add a movie to a list of movies, navigate to a detail view, and then edit the name of that movie:

I will not go into detail here about how the app and the StorageProvider class works other than to say that I think it is a pretty fair example of how to separate the data layer from the view layer of an app. Hopefully the provided comments are clear.

If you examine any of the views in the app, you will see that the Xcode Previews code is commented out.

Let's start correcting that by completing the first of three steps.

Using Core Data Storage In-memory

Core Data's underlying storage, by default, persists changes made. If it didn't, it would not be a very useful framework!

We could drive Xcode Previews with sample data from Core Data, but if we allowed the changes to persist, every time we reload a view in a preview, more data would be added to our Core Data store.

This is generally not ideal, since an Xcode Preview will be reloaded many times.

Open StorageProvider.swift and navigate to the initializer on or around line 20:

Modify the list of parameters for the initializer to the following:

init(inMemory: Bool = false) {

By providing a default value for the newly introduced parameter, existing call sites do not need to be updated. A default value of false is logical as when the app is running outside of a preview, we want changes to the Core Data store to persist.

Note that the first thing that occurs within the initializer is that an NSPersistentContainer instance is created:

// Access the model file
persistentContainer = NSPersistentContainer(name: "PracticalCoreData")

Immediately after that line of code, add the following:

// Don't save information for future use if running in memory...
if inMemory {
	persistentContainer.persistentStoreDescriptions.first!.url = URL(fileURLWithPath: "/dev/null")
}

The edits we have made here will allow us to create an instance of StorageProvider whose data, when changes are made, are not persisted because they are kept in-memory only, as opposed to being written to a long-term storage medium.

On to the second step...

Generating Sample Data

The second property of the StorageProvider class is as follows:

// For initializing the Core Data stack and loading the Core Data model file
let persistentContainer: NSPersistentContainer

Immediately below that property, add the following closure:

// For use with Xcode Previews, provides some data to work with for examples
static var preview: StorageProvider = {
	
	// Create an instance of the provider that runs in memory only
	let storageProvider = StorageProvider(inMemory: true)
	
	// Add a few test movies
	let titles = [
				"The Godfather",
				"The Shawshank Redemption", 
				"Schindler's List", 
				"Raging Bull", 
				"Casablanca", 
				"Citizen Kane",
				]
				
	for title in titles {
		storageProvider.saveMovie(named: title)
	}
	
	// Now save these movies in the Core Data store
	do {
		try storageProvider.persistentContainer.viewContext.save()
	} catch {
		// Something went wrong 😭
		print("Failed to save test movies: \(error)")
	}

	return storageProvider
}()

The third step will be completed a bit later on.

At this point, we are ready to try things out with the Xcode Preview for MovieListView.

Navigate to MovieListView.swift and scroll to the bottom of the file.

Uncomment the structure for Xcode Previews, then add the following modifier to the NavigationView:

.environmentObject(StorageProvider.preview)

The entire structure should look like this:

struct MovieListView_Previews: PreviewProvider {

    static var previews: some View {

        NavigationView {
            MovieListView()
        }
        .environmentObject(StorageProvider.preview)
    }

}

The static preview property on the StorageProvider class returns an instance of StorageProvider itself, and that instance is then inserted into the environment – which in turn is accessed by the MovieListView structure when the Xcode Preview runs.

Now start a Live Preview inside the Xcode Previews panel.

You should be able to navigate around the three views of the app, and work with the provided data.

Before continuing, let's explore what happens if we do not load the Core Data store in-memory only.

Return to StorageProvider.swift and, on or around line 24, modify the code such that false is passed as the argument for the inMemory parameter:

// Create an instance of the provider that runs in memory only
let storageProvider = StorageProvider(inMemory: false)

Now try running and re-running the Live View of MovieListView once or twice.

You will not at first see the list of movies change. Run the project in the simulator. Then, return to a Live View of MovieListView in Xcode Previews.

At this point, you should see that the list of movies has been repeated several times. That is because each time a Live View was run, the preview closure was invoked, re-adding several movies to the list of movies in the Core Data store.

I am not certain why it is necessary to run the app in the simulator to see the result of re-running the preview closure several times. I am not at all familiar with the underpinnings of how Xcode works.

Nonetheless, this behaviour is probably not what you want in the long term – so revert the code around line 24 of StorageProvider such that the Core Data store runs in-memory again:

// Create an instance of the provider that runs in memory only
let storageProvider = StorageProvider(inMemory: true)

Close Xcode entirely, then open the project again.

When you run Xcode Previews, you should see just the initial list of movies on MovieListView, with no repeats.

Providing a Single Instance of a Movie

This is the third and final step of the tutorial.

The Movie class is connected to the Movie entity I defined in the Core Data model editor.

Here we are going to extend this class so that a static property provides a single movie that we can use to drive MovieDetailView and MovieEditView.

In the Model group of the Xcode project, create a new file named Movie+PreviewProvider.swift.

Add the following code to the new file:

import CoreData
import Foundation

// Exists to provide a movie to use with MovieDetailView and MovieEditView
extension Movie {
    
    // Example movie for Xcode previews
    static var example: Movie {
        
        // Get the first movie from the in-memory Core Data store
        let context = StorageProvider.preview.persistentContainer.viewContext
        
        let fetchRequest: NSFetchRequest<Movie> = Movie.fetchRequest()
        fetchRequest.fetchLimit = 1
        
        let results = try? context.fetch(fetchRequest)
        
        return (results?.first!)!
    }
    
}

The optionals that are being force-unwrapped on the last line of that static computed property may give you pause.

Let's edit MovieDetailView.swift and then re-visit the code above.

Uncomment the structure for Xcode Previews, then again add the following modifier to the NavigationView:

.environmentObject(StorageProvider.preview)

Additionally, for the movie parameter on MovieDetailView, provide Movie.example as the argument.

The entire structure should look like this:

struct MovieDetailView_Previews: PreviewProvider {
    
    static var previews: some View {
        NavigationView {
            MovieDetailView(movie: Movie.example)
        }
        .environmentObject(StorageProvider.preview)
    }
    
}

When the Xcode Preview is loaded, our sample data is loaded via the preview static property on StorageProvider and again, inserted into the environment.

When MovieDetailView loads, from the Movie extension above, we pass the static computed property example as the argument for the movie whose details will be shown.

Since the sample data is loaded first, in StorageProvider, we can safely force-unwrap the result of the fetch request in our extension to the Movie class.

You should now be able to see MovieDetailView in the Xcode Previews panel.

In much the same way, make edits to the preview structure for MovieEditView, such that the structure looks like this:

struct MovieEditView_Previews: PreviewProvider {
    
    static var previews: some View {
        NavigationView {
            MovieEditView(dismissView: .constant(false),
                          movie: Movie.example)
        }
        .environmentObject(StorageProvider.preview)
    }
}

Conclusion

Going forward, when a new entity is added to the Core Data model, two steps need to occur:

In the preview property of StorageProvider, appropriate sample data must be created and added to the Core Data store.
Write an extension to the class for the newly defined entity, and create a static computed property named example that loads a record from that entity.

Here is a completed version of this project, with all edits described above.

If you have found any errors in this article, or if this article has been useful to you, please let me know. 😀

Changing the Name of an App

2020-09-20T15:20:00.000Z

It's common to want to change the name of your app, as it will be seen by users, long after you selected the name of the project when you first created it.

It's best to keep an app's name brief, otherwise the name will be truncated below the app icon on the device.

For example, right now, you can see the name of the application I'm working with doesn't fit on a device with a smaller screen size.

First, select the blue project file in the top left corner of the Project navigator in Xcode. You can open the Project navigator using the keyboard shortcut Command-1.

Select the General tab.

In the Display Name field, type the new name for the app.

Next, select the Build Settings tab, then search for Product Name.

We'll double-click on the right, and change this value to the new name as well.

Now build your program.

When it has been installed on the device, you will see that it has the newly specified name.

Building an Animated Progress Meter View With SwiftUI

2020-08-17T19:15:00.000Z

When it comes to SwiftUI, I am but a pup, wet behind the ears.¹

However, I encourage my own students to explain their work to others either in writing or with a video. If you can clearly communicate an idea to others using correct vocabulary then you really understand it. So it is in that spirit that I share this article on how to build a composable progress meter view – the first time I've built something in SwiftUI that I feel might be useful to others.

If you are an experienced SwiftUI developer and have feedback about what I've written – I welcome it! I am very much responsible for any errors or inaccuracies.

Goals

After reading this article, you should have an understanding of how to:

combine HStack, VStack, and ZStack views
use animations to highlight a transition between view states
use a GeometryReader container view to ensure the progress meter adapts to varying screen sizes
apply the hue-saturation-brightness model to represent colors
build a lightweight, composable view that accepts parameters

Here is what the finished progress meter looks like – in this case, embedded within a multiplication practice app:

Your browser does not support the video tag.

Showing progress toward a goal

Note that the progress meter view adapts to different device sizes.

Feel free to pause and come back to the tutorial as you complete each logical section. This is a somewhat lengthy article. Let's begin!

Arranging the Views

Begin by creating a new iOS App named ProgressMeter.

NOTE: If you are using Xcode 11, whenever a property of the ContentView structure is referenced below in this tutorial, you must insert self. prior to the property name. This is not required in Xcode 12.

In ContentView.swift you should see something like the following:

import SwiftUI

struct ContentView: View {
    var body: some View {
        Text("Hello, world!")
            .padding()
    }
}

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
    }
}

Let's begin by defining a Rectangle view that will form the first part of our progress meter.

For the time being, we'll work with constant dimensions, and later, introduce GeometryReader to gain a flexible layout. I like to build views against the smallest possible device. In Xcode 12, this is the iPod Touch (7th generation). In Xcode 11, this is the iPhone SE (1st generation) – though you may have to add that simulator manually at first. Based on this handy screen size chart, the maximum available height for these devices will be 548 points (that's 568 less 20 points for the toolbar). Set your run destination now.

Then replace the Text view inside the body property with:

Rectangle()
	.frame(width: 100, height: 548 - 44, alignment: .center)

You'll note the use of an expression, 548 - 44, as the height argument. That's deliberate; we'll revisit this later on.

Moving on, to create the appearance of a progress meter "filling up" we'll need another view.

We're going to make another Rectangle that slides up, revealing the Rectangle below it.

Since the View protocol requires that a single view is returned for the body property, we'll embed both of the rectangles in a VStack:

VStack {
	// "Fill" for progress meter; stationary
	Rectangle()
		.frame(width: 100, height: 548 - 44, alignment: .center)
	// Will slide up
	Rectangle()
		.frame(width: 100, height: 548 - 44, alignment: .center)
}

As you can see, that's not what we want. At the moment the two rectangles are, as we've described with our code, vertically stacked upon one another.

To create the illusion of a filling progress meter, we need to make use of the z-axis. The rectangle that slides up must be at the front, so it is listed second in the ZStack.

Adjust the code to introduce a ZStack:

VStack {
	ZStack {
		// "Fill" for progress meter; stationary
		Rectangle()
			.frame(width: 100, height: 548 - 44, alignment: .center)
		// Will slide up
		Rectangle()
			.frame(width: 100, height: 548 - 44, alignment: .center)
	}
}

Now the two rectangles sit upon one another.

The second rectangle needs a different color. Rather than specifying black or white, we use the primary color, so that the view works on a device in both light and dark modes. By inverting that color, we get the opposite:

// Will slide up
Rectangle()
	.fill(Color.primary)
	.colorInvert()
	.frame(width: 100, height: 548 - 44, alignment: .center)

Now the fill of the rectangle that will slide up matches the background.

At this point, it appears as though no views are present at all!

However, if you place your cursor in Xcode on the line of code that defines either of the Rectangle views, you'll see a faint blue outline showing you where the view is:

The offset view modifier allows us to "[o]ffset [a] view by the horizontal and vertical amount specified in the offset parameter."

Add the following modifier to the second rectangle – the view that will slide up:

.offset(CGSize(width: 0, height: -1 * (548 - 44)))

This immediately places the rectangle that will slide up vertically above the rectangle that will represent the fill of the progress meter. You should see only a black rectangle.

Not what we want, right? It's time to consider the state of our view. As you've heard often while learning SwiftUI, views are a function of state.

Where do we want the rectangle that will slide up to begin?

Directly on top of the rectangle behind it.

Where do we want the rectangle that will slide up to finish?

Positioned vertically above the rectangle behind it.

We need to create state to manage this.

Add the following property to the ContentView struct:

struct ContentView: View {
    
    // For driving animation to reveal rectangle with progress meter fill
    @State private var progressMeterOffset = CGSize.zero

    var body: some View {
        ...
    }
}

Change the offset for the second rectangle so that it's offset is tied to the new progressMeterOffset property, which begins at zero:

.offset(progressMeterOffset)

We're back to having the rectangle that will slide up sitting directly on top of the rectangle behind it – save for the light blue outline, it again looks like there are no rectangles present at all.

What to do?

As soon as that second rectangle appears, we want it to move to its new position. So, add the following modifier below the existing offset modifier:

.onAppear(perform: {
	// Offset is moves the opaque rectangle up
	progressMeterOffset = CGSize(width: 0, height: -1 * (548 - 44))
})

This tutorial probably doesn't feel very useful right now! 😅

The rectangle that is to slide up now jumps immediately to its new offset.

It just looks like there is a single black rectangle – the view that represents the progress meter fill!

The key is the addition of an animation, to make the transition between states occur over some defined period of time.

Adjust the onAppear view modifier as follows:

.onAppear(perform: {
	withAnimation(Animation.easeIn(duration: 4.0)) {
		// Offset is moves the opaque rectangle up
		progressMeterOffset = CGSize(width: 0, height: -1 * (548 - 44))
	}
})

Initially the second rectangle has an offset of zero.

As soon as the second rectangle appears, the offset is changed to the new value.

The change in state between those two offsets is animated over the course of four seconds.

At this point, you should see the following:

Your browser does not support the video tag.

Basic progress meter

As the view that matches the background color slides up using the animation, it reveals the view below it.

That's pretty nice, but before the animation is finished, we have no sense of the size of the progress meter, or how far progress is from "complete".

To do this, we need a border.

Our first instinct would be to do just that – put a border on the rectangle in the background.

Let's try that – add a stroke modifier to the first rectangle:

// "Fill" for progress meter; stationary
Rectangle()
	.stroke(Color.primary, lineWidth: 4)
	.frame(width: 100, height: 548 - 44, alignment: .center)

As you can see, the results are less than ideal.

The rectangle that animates as it moves upward to a new offset makes our progress meter appear to have an open top.

For that reason alone we need a different approach.

Remove the stroke modifier that we just added.

Add a third rectangle enclosed within the ZStack, like this:

// Sits above the rectangle that slides up (in the z-axis)
// This means the rectangle sliding up will pass beneath this view
Rectangle()
	.fill(Color(hue: 0, saturation: 0, brightness: 0, opacity: 0))
	.frame(width: 100 + 2, height: 548 - 44 + 2, alignment: .center)
	.overlay(
		Rectangle()
			.stroke(Color.primary, lineWidth: 2)
	)

You should now have:

Your browser does not support the video tag.

Progress meter with a border

The top-most view on the z-axis has a transparent fill. We see the other views below it, creating the appearance of a rising progress meter.

Let's break that down.

First, the new rectangle that provides the border must have a transparent fill.

Try commenting out the fill modifier:

//	.fill(Color(hue: 0, saturation: 0, brightness: 0, opacity: 0))

You'll notice we have a static image again. That's because the third view in the ZStack, sitting above the other two views, has an opaque fill and border. We can't see what's happening beneath it.

Uncomment the fill modifier. More on hue, saturation, and brightness a little later. The key here is that opacity is set to 0, which means that no matter what the color is, the fill is completely transparent.

Next, you'll notice the width of the frame for this view is an expression, in this case, 100 + 2:

.frame(width: 100 + 2, height: 548 - 44 + 2, alignment: .center)

The rectangles below this one, on the z-axis, also have a width of 100 points.

By adding 2 points to the width of this topmost view, it ensures that the entire border will be visible, and that we can see the views underneath it.

The final view modifier creates the border:

.overlay(
	Rectangle()
		.stroke(Color.primary, lineWidth: 2)
)

Eliminating Magic Constants

When teaching I encourage my students to start simple. That's what we've done here, but a problem is starting to emerge in our code. Let's review – the entirety of ContentView structure should now look like this:

struct ContentView: View {
    
    // For driving animation to reveal rectangle with progress meter fill
    @State private var progressMeterOffset = CGSize.zero
    
    var body: some View {
        VStack {
            ZStack {
                // "Fill" for progress meter; stationary
                Rectangle()
                    .frame(width: 100, height: 548 - 44, alignment: .center)

                // Will slide up
                Rectangle()
                    .fill(Color.primary)
                    .colorInvert()
                    .frame(width: 100, height: 548 - 44, alignment: .center)
                    .offset(progressMeterOffset)
                    .onAppear(perform: {
                        withAnimation(Animation.easeIn(duration: 4.0)) {
                            // Offset is moves the opaque rectangle up
                            progressMeterOffset = CGSize(width: 0, height: -1 * (548 - 44))
                        }
                    })

                // Sits above the rectangle that slides up (in the z-axis)
                // This means the rectangle sliding up will pass beneath this view
                Rectangle()
                    .fill(Color(hue: 0, saturation: 0, brightness: 0, opacity: 0))
                    .frame(width: 100 + 2, height: 548 - 44 + 2, alignment: .center)
                    .overlay(
                        Rectangle()
                            .stroke(Color.primary, lineWidth: 2)
                    )

            }

        }

    }
}

We've repeated several expressions. Let's say we wanted to make our progress meter a little wider. We'd have to change arguments in three locations!

This calls for the introduction of a constant property.

Add the following to the structure:

// Width of the meter
let meterWidth: CGFloat = 100

Anywhere that you see the constant 100, replace this with the name of the constant, meterWidth.

We can do the same thing for the thickness of the border:

// Thickness of meter's border
let borderWidth: CGFloat = 2

Anywhere that you see the constant 2, replace this with the name of the constant, borderWidth.

Finally, the same can be done for the padding above and below the meter, which is currently set to 44 points² (22 points above, and 22 points below, since the view is vertically centred):

// Padding above and below progress meter
let verticalPadding: CGFloat = 44

Anywhere that you see the constant 44, replace this with the name of the constant, verticalPadding.

The code should now look like this:

struct ContentView: View {
    
    // For driving animation to reveal rectangle with progress meter fill
    @State private var progressMeterOffset = CGSize.zero
    
    // Width of the meter
    let meterWidth: CGFloat = 100

    // Thickness of meter's border
    let borderWidth: CGFloat = 2
    
    // Padding at top of progress meter
    let verticalPadding: CGFloat = 44
    
    var body: some View {
        VStack {
            ZStack {
                // "Fill" for progress meter; stationary
                Rectangle()
                    .frame(width: meterWidth, height: 548 - verticalPadding, alignment: .center)

                // Will slide up
                Rectangle()
                    .fill(Color.primary)
                    .colorInvert()
                    .frame(width: meterWidth, height: 548 - verticalPadding, alignment: .center)
                    .offset(progressMeterOffset)
                    .onAppear(perform: {
                        withAnimation(Animation.easeIn(duration: 4.0)) {
                            // Offset is moves the opaque rectangle up
                            progressMeterOffset = CGSize(width: 0, height: -1 * (548 - verticalPadding))
                        }
                    })

                // Sits above the rectangle that slides up (in the z-axis)
                // This means the rectangle sliding up will pass beneath this view
                Rectangle()
                    .fill(Color(hue: 0, saturation: 0, brightness: 0, opacity: 0))
                    .frame(width: meterWidth + borderWidth, height: 548 - verticalPadding + borderWidth, alignment: .center)
                    .overlay(
                        Rectangle()
                            .stroke(Color.primary, lineWidth: borderWidth)
                    )

            }

        }

    }
}

The advantage here is we can quickly make adjustments. Want less padding? Change verticalPadding in one location. Want a thicker border? Adjust the borderWidth property.

Beyond convenience for adjusting the look of our progress meter, the code is simply more readable. We no longer have to think about what 100 or 44 represent when reviewing an expression. We can see what's happening by the property names we chose – the expressions are self-documenting.

Try changing some of the new constants you just added and observing how that affects the animation.

You're probably wondering – what about 548? When are we going to address that?

Using GeometryReader to Create an Adaptive Layout

Change the iOS simulator to be the iPhone 11 Pro Max, or really any device larger than the iPod Touch.

You see the problem with the remaining "magic constant" of 548:

Your browser does not support the video tag.

Progress meter on a larger device

548 points of height works on an iPod Touch, but not the iPhone 11 Pro Max.

To correct for this, we can place the VStack and all its contents inside a GeometryReader container view:

var body: some View {
	GeometryReader { geometry in
		VStack {
			...
		}
	}
}

NOTE: If you are using Xcode 11, after you place the VStack inside GeometryReader, you'll need to update references to properties to include the self. prefix. If you're not sure what this means, don't worry, you'll see the red compiler warnings soon enough. 😅

The developer documentation describes GeometryReader as "[a] container view that defines its content as a function of its own size and coordinate space."

In practice, that means we can use the geometry parameter to gain information about the size of the surrounding view.

Temporarily comment out the VStack and all it's contents, so that the only view inside GeometryReader is a Text view like this:

Text("Height is \(geometry.size.height)")

On an iPhone 11 Pro Max, there are 818 points available to work with, vertically.

If you wish, try changing to other simulators. You will see that the reported geometry.size.height value changes accordingly.

Now remove the Text view and uncomment the VStack and all its contents.

Replace any reference to the constant 548 with geometry.size.height instead.

Try changing to other simulators.

You will see that the progress meter now always fills the available vertical space. That's the power of GeometryReader!

As you've surely also noticed, since moving our views inside GeometryReader, the meter is no longer centred in the middle of the screen³.

I'm honestly not sure why this happens, but we can correct for it by judicious use of Spacer views.

To split the vertical padding evenly as we had before, just add Spacer() views before and after the ZStack, within the VStack:

VStack {
	
	Spacer()
	
	ZStack {
		...
	}
	
	Spacer()
	
}

To centre the meter once again, we need to introduce an HStack.

We'll sandwich the ZStack between two Spacer views inside the horizontal stack:

VStack {
	
	Spacer()
	
	HStack {
		
		Spacer()
		
		ZStack {
			...
		}
		
		Spacer()

	}
	
	Spacer()
	
}

And just like that, we're back to having our progress meter positioned as before⁴ except now it responds to varying device sizes:

Creating a Colorful Progress Meter

In my youth I played video games more often. I recall enough about gaming to know that a "health meter" is usually red when a player is low on health, and green when things are going well.

That's the inspiration for this next change to the progress meter.

The closer it gets to "full" the more green we want the fill to be.

I won't go into a full discourse on how to represent color on a computer here, because I am not an expert, and this article is already getting a bit long!

Suffice it to say, the hue of a color can be represented as a value between 0 and 360 degrees. 0 is red, 60 degrees is yellow, 120 degrees is green, and so on. You can see a few examples and read more here, if you like.

What we will do is fill the progress meter with a gradient.

The bottom, or start, of the gradient will always be red, so, 0 degrees for a hue.

The top, or end, of the gradient will be green if the progress meter is "full", or something less than green if the progress meter is not full.

First, we'll introduce a couple of constants to express how "full" the progress meter is. Since I wrote this progress meter initially to serve on a results screen for a multiplication practice app, the constants are named to reflect that:

// Needed data to calculate colors and size of meter
let correctResponses: Int = 10
let questionCount: Int = 10

The percentage of a full progress meter can be expressed with a computed property:

// Percentage of full progress meter
// If the progress meter is full, this will equal 1.0
private var fractionOfFullMeter: Double {
	Double(correctResponses) / Double(questionCount)
}

And the ending color of the gradient can also be expressed using a computed property:

// Ending color for progress meter
// 120/360 degrees or 0.333 in Color struct terms is green
// which is the top of the meter when all questions are correct
private var endColor: Color {
	
	// If you had 10 out of 10 questions correct, this will equal 120.0 degrees
	let endingHue = fractionOfFullMeter * 120.0
	
	// Color is:
	// hue: 0-360 degrees, expressed as a value between 0 and 1
	// saturation: 0-100%, expressed as a value between 0 and 1
	// brightness: 0-100%, expressed as a value between 0 and 1
	// see: https://russellgordon.ca/lcs/HSB_Color_Model_Summary_Swift.pdf
	return Color(hue: endingHue / 360.0, saturation: 0.8, brightness: 0.9)
}

In the ZStack, for the rectangle representing the fill of the progress meter (the first rectangle) add the following view modifier right before the frame modifier:

.fill(LinearGradient(gradient: Gradient(colors: [Color.red, endColor]),
					 startPoint: .bottom,
					 endPoint: .top))

If you added the constants, the computed property, and the fill modifier correctly, you should now have this:

Your browser does not support the video tag.

Applying a gradient

As the progress meter approaches completion, the colour moves from red to green.

We are not quite finished, however. Reduce the correct responses constant:

let correctResponses: Int = 3

Review the animation:

Your browser does not support the video tag.

An incorrect height

At present, while colors are accurate, the progress bar always appears to be complete.

The gradient works as expected, since it barely gets out of the orange range of hues, given that there were only three correct responses out of ten.

However, the height of the progress bar is not accurate.

We can correct that by using the fractionOfFullMeter property to reduce the height of the rectangle that contains the fill of the progress meter.

Change the view modifier for the size of the frame on the first rectangle from the following:

.frame(width: meterWidth, height: geometry.size.height - verticalPadding, alignment: .center)

... to this instead:

.frame(width: meterWidth, height: CGFloat(fractionOfFullMeter) * (geometry.size.height - verticalPadding), alignment: .center)

The animation will now look like this:

Your browser does not support the video tag.

Oooh, so close!

Can you predict what we need to do?

The rectangle containing the view is centred vertically in the ZStack that contains it.

There are a couple of ways this could be handled, but we'll correct the problem by adding another rectangle above the progress meter, inside a VStack.

Change this:

ZStack {

	// "Fill" for progress meter; stationary
	Rectangle()
		.fill(LinearGradient(gradient: Gradient(colors: [Color.red, endColor]),
							 startPoint: .bottom,
							 endPoint: .top))
		.frame(width: meterWidth, height: CGFloat(fractionOfFullMeter) * (geometry.size.height - verticalPadding), alignment: .center)
		
	...

... to this:

ZStack {

	VStack(spacing: 0) {
		
		// This pushes the filled part of the progress meter down
		Rectangle()
			.frame(width: meterWidth, height: (geometry.size.height - verticalPadding) - CGFloat(fractionOfFullMeter) * (geometry.size.height - verticalPadding), alignment: .center)
		
		// "Fill" for progress meter; stationary
		Rectangle()
			.fill(LinearGradient(gradient: Gradient(colors: [Color.red, endColor]),
								 startPoint: .bottom,
								 endPoint: .top))
			.frame(width: meterWidth, height: CGFloat(fractionOfFullMeter) * (geometry.size.height - verticalPadding), alignment: .center)

	}
	
	...

Note the addition of the spacing parameter with an argument of 0 on the VStack. That ensures the two rectangles in the VStack will sit snugly against one another.

At this point, you will see the following:

Your browser does not support the video tag.

The new rectangle's fill was left black so that we can see where it exists.

Now, we can add a couple of view modifiers to change it's fill to match the background color of the view:

// This pushes the filled part of the progress meter down
Rectangle()
	.fill(Color.primary)
	.colorInvert()
	.frame(width: meterWidth, height: (geometry.size.height - verticalPadding) - CGFloat(fractionOfFullMeter) * (geometry.size.height - verticalPadding), alignment: .center)

Our progress meter, from it's outward apperance at least, is now complete!

Try changing the correctRespones constant to different values to see the effect it has on the animation:

Your browser does not support the video tag.

The completed progress meter

What the animation looks like with three, seven, and ten out of ten questions completed correctly.

Creating a Composable View

We now have a progress meter that is reasonably well put together, but if we wish to combine it with other parts of an app (as I did with a multiplication practice app) it would be best if what we've done so far was defined as part of its own type. Let's call this new type ProgressMeter.

Rather than provide a long series of steps to follow, you can just download a complete Xcode 12 project where this has already been done, or here for an Xcode 11 project. If you prefer, you can get the Xcode 12 project from GitHub here, or the Xcode 11 project from GitHub here.

Note that in ProgressMeter.swift, the constants:

// Width of the meter
let meterWidth: CGFloat = 100

// Thickness of meter's border
let borderWidth: CGFloat = 2

// Padding above and below progress meter
let verticalPadding: CGFloat = 44

// Needed data to calculate colors and size of meter
let correctResponses: Int = 10
let questionCount: Int = 10

... have been changed to variables without initial values:

// Width of the meter
var meterWidth: CGFloat

// Thickness of meter's border
var borderWidth: CGFloat

// Padding above and below progress meter
var verticalPadding: CGFloat

// Needed data to calculate colors and size of meter
var correctResponses: Int
var questionCount: Int

That means to use an instance of the ProgressMeter view, we must provide values for those properties.

This is done in ContentView.swift where we now just create an instance of ProgressMeter and pass in the required arguments:

ProgressMeter(meterWidth: 100, borderWidth: 2, verticalPadding: 44, correctResponses: 10, questionCount: 10)

In this way, we now have a self-contained view that can be neatly composed together with other views in a larger app and re-used in multiple future projects.

Conclusion

This turned out to be a rather lengthy tutorial. If you've found it helpful, interesting, or have found an error please tell me. Thanks for reading this far! 😅

I've been working through Paul Hudson's 100 Days of SwiftUI tutorials. Highly recommended.^
Why 44 points? No particular reason – that's just the amount of padding I felt looked good when I initially wrote this progress meter view.^
This doesn't seem to happen with Xcode 11, and probably represents a bug in the beta of Xcode 12 I was using when authoring this article. So, if you're seeing the progress meter stay centred, feel free to skip ahead to this part of the tutorial.^
I love spacer views.^

Adding a Physical Device as a Run Destination

2020-09-19T19:29:00.000Z

To run applications you write in Xcode on your iPhone or iPad, a few one-time-only setup steps are required.

First, be sure Xcode is open.

Select the menu sequence Window → Devices and Simulators.

Then, connect your iPhone or iPad to your Mac using a cable.

The first time you do this, you will see an image something like this:

The yellow banner message is telling you that certain required files are being copied to and from your device.

That process may take a few minutes to complete; be patient. When it is finished, the yellow banner will disappear.

Next, you can select the device you've connected as a run destination.

At the top left of the primary Xcode window, click the list of devices:

Then select your device from the list (a connected physical device is always at the top of the list):

Now build the application:

To use your developer certificate with the device, you'll need to allow access to your computer's keychain. Select Always Allow so that you don't have to do this every time you build an app for the device:

Next, you will likely see a message indicating that Xcode cannot run the application on the device, because, essentially, your iPhone or iPad currently does not "trust" the Mac that you are developing on to install applications upon it.

To create that trust, follow the instructions shown here.

The next time you build your application with your iPhone or iPad as the selected run destination, after a few seconds, you should see it open on your device.

Have fun! 🚀

Prevent the Dreaded Blue Screen of Death

2020-08-10T22:30:32.000Z

No, not that blue screen of death.

This one.

We've all been there: in front of a class, or perhaps colleagues, hitting our speaking groove – and then the slide deck drops out and the projector complains that there is no input.

This is caused when the connected computer goes to sleep due to a lack of keyboard or trackpad input.

In the run up to a class or presentation, remembering to adjust energy saver settings can be pretty far down the priority list.

A utility called Caffeine, appropriately, comes to the rescue.

This is a small program that lives in the menu bar of your Mac. The preferences are very basic:

To get Caffeine, download it, then double-click the Caffeine.dmg file. Drag the Caffeine icon to your Applications folder.

When you run the program for the first time, you can select your preferences.

As a matter of course while teaching, I always keep Caffeine enabled.

If I want my laptop to sleep, I close the lid or explicitly put it to sleep.

And I never, ever encounter the blue screen of death. 😅

Embiggen Text Like a Pro

2020-08-11T22:30:32.000Z

A noble spirit embiggens the smallest man.

– Springfield town motto

In the seventh-season episode Lisa the Iconoclast The Simpsons' writers popularized a word that, it turns out, has been used as far back as 1884.

Why mention this? I've a perfectly cromulent reason.

When teaching, whether live or through video, it's helpful at times to make something that's rather small on your screen temporarily show up much larger.

Need to highlight a key term? Indicate that a new section of a video is beginning? Have an off-the-cuff need to send students to a website?

These are all use cases for embiggening text.

Installing LargeType2

On macOS¹ the LargeType2 utility makes this possible. Here is an example:

Download the program, open the disk image, and drag the LargeType icon to your Applications folder.

Now navigate to your Applications folder and open LargeType2. On more recent versions of macOS, you will encounter a message like this one:

This message appears on first run because LargeType2 has not been updated recently. While it still works just fine on macOS, this warning message appears because the application is not digitally signed by the developer. I have been using this application for years. It's not malware. You can work around the security warning by two-finger tapping, or context-clicking, the application, and choosing Open:

In the dialog that appears, select Open again.

At this point you will see a small instructions window. You need to log out of macOS and then log back in. If you are the only user of your Mac, and don't use a login window, you'll need to restart your computer.

Configuring a Keyboard Shortcut

Now that LargeType2 is installed, you can highlight any text, two-finger tap or context-click, select Services, and then LargeType.

That's a bit awkward, so let's set up a keyboard shortcut.

To do so:

Open System Preferences.
Navigate to the Keyboard preference pane.
Select the Shortcuts tab.
Select Services at left.
In the list at right, scroll down to LargeType.
Select the LargeType entry. Click where it says Add Shortcut.
Now choose a keyboard combination that will embiggen text. I like Control-Option-Command-L. These are the three modifier keys to the left of the spacebar on my keyboard, so it's easy to remember, and won't conflict with other application keyboard shortcuts.

That's a long list of steps, so if you prefer, here's a short video showing how that works.

The Payoff

Now you're all set for rapid embiggening!

Just select text in any application, hit your keyboard shortcut, and enjoy your very large text.

Sorry, Windows users. I've been on macOS for fifteen years so I'm not going to be very useful to you. If anyone knows of a utility similar to LargeType that runs on Windows, let me know, and I'll insert an addendum to this tip. ^

Snow Clearing and Computer Studies Enrolment

2019-08-14T13:22:00.000Z

What impacts Computer Studies enrolment in Ontario?

There's the chicken and egg problem, for one. Our courses are not prerequisites for STEM-related majors in Ontario universities... because not all secondary schools in Ontario offer Computer Studies courses. It's hard to require a course that is not offered. That's only going to get worse.

There's a perception that our courses are difficult. Any student who has spent inordinate amounts of time struggling with syntax will agree that can be true (even if it's really the tools that are deficient and not the programmer).

And then... there's this, from the lede on a recent episode of 99% Invisible by Roman Mars, interviewing Caroline Criado Perez:

Today’s show is about a design flaw that might be, and I’m not exaggerating here, the single-most common design flaw in human history. It potentially affects everything we have ever built. Its consequences are felt by more than half of people worldwide...

What's this now?

There's a town in Sweden. Karlskoga. It snows there. For a long time, like many places, when it snowed, major roads were cleared first. In the process of doing a gender analysis of local town policies, someone made a joke – snow clearing. It couldn't possibly have anything to do with gender, could it?

Karlskoga city planners looked at the types of tasks women handle on a daily basis. Tasks like shuttling children to school, stopping off to pick up groceries, dropping in to check on elderly relatives. Tasks that were often completed on foot or by taking public transit on smaller residential roads.

It turns out... it's a lot harder, and much less safe, to push a stroller through a foot of snow than it is to drive a car down a major arterial road. Karlskoga decided to clear minor roads and residential areas first, and saw a significant decrease in healthcare costs, savings that far outweighed the cost of winter road maintenance. Everyone benefits.

What if, by making deliberate choices about how we describe, promote, and deploy our Computer Studies courses, we bring in not just more young women, but more students overall to this vital field of endeavour?

Context Over Tools

I recently visited Austin, Texas to attend a weeklong workshop with teachers using Swift for instruction in the College Board's Advanced Placement Computer Science Principles course.

The workshop was hosted by Apple, and we naturally spent time examining their curricular resources and tools.

I was pleased to see that the agenda focused not just on tools, but also on the bigger picture of inclusion in the software industry and in our classrooms. Douglas Kiang gave an excellent talk on fostering a sense of belonging for young women in computer science courses.

With permission from Douglas, I will include text from a few of his presentation slides here.

The following is an older description for a course offered at Douglas' school:

Introduction to JavaScript (1 credit)

This course introduces students to the basics of JavaScript, HTML,   and CSS. It covers basic computer programming concepts such as variables, loops, operators, arrays, functions, and conditional statements. It features best practices for current web-standards compliance techniques using the HTML DOM (Document Object Model) and offers interested students the opportunity to dive deeper into asynchronous data requests using AJAX and jQuery.

The question Douglas posed: Who is your audience?

To whom does that original course description speak?

As teachers, we understand it. Would a student?

It's kind of like seeing a course description like this:

Introduction to Japanese (1 credit)

基本クラスは、基本的な⽂文法に注意を払いながら、コミュニケーションスキル (主に会話型)を身に付けることを⽬目的としています。中級クラスは、基本レベルの⽂文型を組み合わせることにより、実⽤用的な会話能⼒力力をさらに⾼高めることを⽬目的としています。各グループは週に1回、⽇日本⼈人ボランティアによる約90分のレッスンを受けます。参加者のスケジュールが特定の⽇日の出席を許可しない場合、会議は⾒見見逃される可能性があります。授業内容は、グループの規模と参加者の興味と能⼒力力に応じて調整されます。基本的な焦点は、⽇日常⽣生活や勉勉強に必要な⽇日本語の会話⼒力力を伸ばし、⽇日本の⽂文化や伝統について指導することです。

Douglas and his colleagues revised the course description to read as follows:

Building Websites for Non-Profits (1 credit + community service)

Work closely with a community organization to help design a website that meets their needs. Gain programming experience while designing a front-end web interface that retrieves data from a server. Previous projects have included an event registration page for Malama Honua, an after-school program site for the Boys and Girls Club, and a web portal for the Arcadia Retirement Residence.

Same course, same content, different description.

The result? Punahou School school saw many more young women enrol, as well as more young men.

Students in Ontario will always see the standard Ministry of Education course descriptions in official documentation.

However, it's the very definition of picking the low hanging fruit for us, as teachers, to provide the Guidance staff, students, and parents at our schools with accessible and welcoming course descriptions, and ensure that these are made visible to students well in advance of course selection time.

How we describe what we do in our courses matters.

Build Community

For the first time in my teaching career¹, the gender balance in my Computer Studies classes across grades 10 and 11 is precisely even. At last check, there are seven boys and ten girls enrolled in ICS2O; eleven boys and eight girls in ICS3U.

With few other variables in the mix, I'm left to cautiously conclude that new opportunities we offered last year at Lakefield College School have made a difference for enrolment this year.

First, in December 2018, my school partnered with the Hackergal team to participate in a hackathon. In their words:

A Hackathon is an event in which groups of people come together to solve a problem. The term is largely used in the tech industry to describe a fast-paced event in which computer programmers or “coders” work together to create a functioning product. During a Hackergal Hackathon, groups of girls work together over a day to apply coding skills they’ve learned leading up to Hackathon Day. Teams will work together to create an interactive project with a theme that is revealed on the morning of the Hackathon.

To prepare for the hackathon, we had twelve grade 9 girls complete five lessons over roughly ten hours of co-curricular time.

The Hackergal organization provided all of the preparatory material and tools free of charge, and were extremely strong communicators leading up to the event itself.

On the day of the hackathon, the girls were excused from class and completed the challenge along with a much larger group of young women across the country through an online presence.

Our students are taking part today’s @thehackergals’ Canada-wide hackathon with girls from more than 100 schools across Canada. #becausewecan #hackergal2018 pic.twitter.com/mVi7SbfXQS
— Lakefield College (@LakefieldCS) December 12, 2018

As a strategy, advocating for and offering an event like this takes more time than re-writing course descriptions – but it created an amazing sense of community among the young women at our school before they even got to the point of considering enrolment in a computer studies course.

Provide a Trial Run

Developers often allow users to try out their software prior to asking for the commitment of a payment.

In the same vein, at LCS, we offered a coding-themed day to coincide with Computer Science Education Week. The timing here is deliberate – positioned in advance of (but not too far before) course selection on the school calendar.

On an intercession day at LCS – when the entire school has a break from regular classes, but the learning continues through other tasks – students had (among other options) the opportunity to participate in a day of coding-related activities.

Tasks offered included the creation of physical artwork by generating SVG files through code and then sending the files to a plotter:

Your browser does not support the video tag.

Generating Physical Artwork Using Code

Any programming environment capable of generating an SVG file can be used to drive the output on an AxiDraw plotter.

Senior students enrolled in Computer Studies courses mentored junior students who expressed an interest in starting to prepare for computer science contests, using online coding environments like repl.it and past problems published by the CEMC.

Another option saw students use Processing to explore introductory tutorials explaining how to produce graphics and animations, with more experienced students digging into the work of generative artists or simulating natural systems.

The centrepiece of the day involved a visit from a Dr. Rachel Wortis from Trent University who gave a hands-on talk about encryption and quantum computing.

The day, to be honest, was a lot of work to organize, but it doesn't have to be that way.

In the future, we plan to run a similar day at LCS, but may make more use of externally sourced content that does not necessarily involve coding, such as the popular CS50 Puzzle Day authored by David J. Malan and his team at Harvard, or the College Puzzle Challenge provided by Microsoft.

The theme of the series of activities was to provide students with a taste of what computer studies is all about before those students need to make a choice about course selection.

How we promote computer studies matters.

Positive Role Models

When it comes to recruiting women into computer science, whether a role model projects current stereotypes of the field may be more important than whether that role model is female or male. Role models may be successful if they elicit a sense of belonging.²

Douglas Kiang emphasized those points during his talk in Austin in July.

During that same intercession day in early December at LCS we arranged for several graduates of my past classes to speak with current students through video chats.

The speakers – two young women, three young men – do not all exclusively write code in their positions. None hew to Hollywood hacker stereotypes. Of the speakers we were fortunate to ask questions of:

two are developers at Apple (iPhone and Watch teams)
one is an analyst at KPMG
one is a project manager at Yelp
the final speaker works in a variety of roles exploring the intersection of visual arts, business, and technology (she is about to graduate from this fascinating program at USC)

Of course, I had not yet heard Douglas make his point when I organized speakers. What he said resonated, however, and the response from LCS students was positive.

Question and Answer

A past graduate of my computer studies classes talks with current LCS students.

The key here – whether we find role models in past students, parents in a school's community, or members of the public – it is helpful to show current students where our courses lead – before they are asked to decide on course selection.

Embrace the Depth of the Field

If you've been paying close attention, you've noticed that I have used the term computer studies throughout this article – not computer science.

That is deliberate – the former is a superset of the latter.

Computer studies is about how computers compute. It is not about learning how to use the computer, and it is much more than computer programming. Computer studies is the study of ways of representing objects and processes. It involves defining problems; analysing problems; designing solutions; and developing, testing, and maintaining programs. For the purposes of this document, the term computer studies refers to the study of computer science, meaning computer and algorithmic processes, including their principles, their hardware and software designs, their applications, and their impact on society.³

Is that quote familiar?

If you're a teacher in Ontario, it should be – it's from page 3 of the Ontario Computer Studies curriculum!

That bit of rhetorical flourish exists in this article with feeling.

I know that it is not easy to be a teacher, let alone a Computer Studies teacher.

However, if all that we focus on are algorithms, code, and tools – if we address but don't emphasize the rest of the curriculum – we are doing our students a grave disservice.

Over March Break this year, the Hackergal organization ran a terrific one-day workshop for teachers. The highlight was hearing from a panel of dynamic women working in the software industry:

Today’s workshop @RyersonDMZ is for the educators! This morning we will be hearing from a panel of inspiring women in tech to discuss what motivates them, equipping the next generation, & where the future of technology is heading! Let’s go @CIBCLiveLabs @cse_cst @riyakarumanchi! pic.twitter.com/dQ0AEvTesA
— Hackergal (@thehackergals) March 13, 2019

One common theme that emerged from the comments of the panelists was that they all started in the field of computer studies after high school⁴.

Why was that? The specific examples varied, of course, but the gist? Computer studies classes in their schools focused nearly entirely on writing code, and there was little to no emphasis on the idea that computer studies is ultimately about talking to people to identify problems and finding ways to solve those problems using technology.

Look, we know Apple has an excellent marketing team – but this video nails it:

At my school, I am working to build a three-year computer studies program that provides the full experience of problem solving and software development. I want students to graduate having published meaningful applications with a portfolio of code they can use when speaking to prospective future clients or employers.

So, in grade 10 this past year, we started early, working deliberately to improve our skill in offering an effective critique of each others' work.

Ron Berger's book, An Ethic of Excellence, is well worth your time – a brief but powerful text on how to guide students in creating meaningful, high-quality products.

I like to use this video, featuring Ron, to introduce effective critique to my students:

Eyes roll when my students see the age of the children in the video, but they are wowed by the end.

As the year progressed, we practiced running usability trials for software that my students had authored, of the sort described here:

I make a point of building the opportunity for feedback and revision into the timeline of a task. This figure is instructive:

The design process is described in the preamble to the Ontario Technological Education curriculum.

Here is one example of the outline and rubric for a task in Introduction to Computer Studies. This was filled out incrementally for every student as they submitted each required deliverable.

That rubric may look a little different than you're used to – I am not fond of the traditional four-column rubric. I recommend taking a look at John Rampelt's deep dive into single-point rubrics.

After gaining confidence with software tools like Alice and Thunkable, and giving and receiving effective feedback first within our own class, then with students in other classes at LCS, I felt that my grade 10 students were ready to work within our local community.

Through a collabration with two amazing teachers at a nearby elementary school, each my grade 10 students were tasked with being a contractor for a group of two to three grade 4 students. Based on requirements provided by the younger students, students in my class would design, prototype, and deliver a custom educational application.

My students visited the grade 4 classes a total of four times to:

Meet their clients and document their requirements.
Present a paper prototype and receive feedback on their design.
Present a functioning, but incomplete, software prototype, and receive feedback on their work to date.
Deliver the final application.

Each visit lasted about forty-five minutes, and was spaced approximately two weeks apart on the calendar.

The younger students asked for a wide variety of applications, including ideas like:

a game that makes learning the Cartesian co-ordinate system fun
a narrative where aliens landed and the student must find a way to prevent their family from being abducted
an interactive hockey game, where correctly answering occasional math facts gave each player greater speed and dexterity when moving the puck

Here are some photos from our visits to the elementary school:

An older student looks on while the younger student provides usability feedback. Photo by Will Callaghan.

Thunkable allowed my students to produce apps that ran on mobile devices for the younger students. Photo by Will Callaghan.

An LCS student explains how some of the code he wrote works. Photo by Will Callaghan.

Good humour while a prototype of an interactive hockey game is demonstrated. Photo by Will Callaghan.

The hope was that by engaging with an external audience in a fairly authentic manner, my students would be motivated intrinsically to do their very best for this culminating task in the course.

Your browser does not support the video tag.

Mario Treasure Hunt

The completed version of the game that teaches Cartesian co-ordinates through play.

What was the response like from my Grade 10 students?

Here are some comments offered through an anonymous end-of-year survey:

This culminating task was more meaningful because it was more interesting and realistic. I felt like I was doing a real job and I loved working with the kids.

Another offered:

For me, this culminating task was more meaningful, because I got to actually talk to people and it felt like I was really communicating with a user. Being with kids who have a lot of ideas was also helpful because then I could make my game more specific.

There were other similar responses.

100% of my students felt a similar culminating task should run in this course next year.

All of this makes it clear to me that how we deploy our courses – how we ask our students to demonstrate their mastery of expectations – matters a lot.

Conclusion

As described in the episode of 99% Invisible, it was not the benefits to residents of Karlskoga, or the town's bottom line, that was the point.

It's that well-intentioned city planners actually forgot to remember that women exist.

This would never have happened were there equitable gender representation in the city planner's office.

The podcast episode describes several other examples of real harm that has come to women due to design that neglects to consider fifty percent of our planet's population.

We cannot let the same thing happen in the software industry.

As teachers, we have a moral imperative to do everything we can to make our computer studies classes welcoming to young women and to other under-represented groups.

Talking about historical gender balance in my Computer Studies classes is complicated by the fact that while I have been a teacher at co-ed schools, I have also taught at an all-girls and an all-boys school. In Canada, some might call that a hat trick.^
Cheryan, Sapna, Benjamin J. Drury, and Marissa Vichayapai. “Enduring Influence of Stereotypical Computer Science Role Models on Women’s Academic Aspirations.” Psychology of Women Quarterly 37, no. 1 (March 2013): 72–79. doi:10.1177/0361684312459328.^
The Ontario Curriculum, Grades 10 to 12, Computer Studies (Revised) (Toronto: Ministry of Education, 2008), 3.^
Except Riya Karumanchi, who is still in high school – but she is a pretty amazing special case.^

Integrate Coding in Mathematics using Python, Jupyter Notebooks, and Google Colab

2024-08-15T11:22:00.000Z

Agenda

For this session, here is the plan:

Timing	Goals
10 minutes	Introduction
30 minutes	Try out some notebooks
10 minutes	Pair, share, questions
30 minutes	Begin authoring a notebook of your own
10 minutes	Wrap-up

Introduction

How can we meaningfully integrate coding into mathematics classes, and allow students to make their thinking visible?

From the MTH1W curriculum, regarding the selection of tools and strategies:

All students should be encouraged to select and use tools to illustrate mathematical ideas. Students come to understand that making their own representations is a powerful means of building understanding and of explaining their thinking to others. Using tools supports students as they:

identify patterns and relationships;

make connections between mathematical concepts and between concrete and abstract representations;

test, revise, and confirm their reasoning;

remember how they solved a problem;

communicate their reasoning to others...

The combination of:

... allows students to share their approach to solving a problem and permits teachers to facilitate all of this with a minimum of fuss and bother.

In time, students come to see coding not just as something that is done in addition to mathematics but as a viable tool for exploring mathematical relationships and for problem-solving.

Building Blocks and License

For the the 2023-24 school year, a part of my role at Lakefield College School involved supporting my colleagues in the Mathematics department as they worked to meaningfully integrate coding into MTH1W.

I started by consulting the work of Grant Hutchison and the Association of Computer Studies Educators at the Coding Integration website.

Copyright for this post remains with me, Russell Gordon, but all of the Jupyter notebooks I will share, some of which are built upon work from the Coding Integration website, are published under the Creative Commons Attribution Non-Commercial Share-Alike 4.0 International license.

Practical Considerations

As a teacher I want use of a Jupyter notebook to be just as easy as distributing paper to and collecting that paper from my students. For students, use of the notebook should be as close to working on paper as possible, so as to reduce their cognitive load.

Using Google Drive to author and store Jupyter notebooks, Google Classroom to distribute and collect notebooks from students, and Google Colab to interact with a notebook, gets pretty close to the ease of working with paper.

Even without Classroom, you can create and work with Google Colab documents in Drive the same way you can with Sheets, Docs, or Slides documents:

[!TIP]

Depending on your school or school district settings, in order to create Google Colab documents from the menu shown above, you may need to ask your IT administrator to enable this extension:

Even without this extension installed, it is still possible to duplicate existing Colab documents you have added to your Google Drive.

In fact, duplicating and editing existing Colab documents is my recommended approach to authoring an activity. More on this later in the session.

[!NOTE]

Of course, not every school or school district permits use of Google Workspace tools.

Python Notebooks can also be used within the Callysto environment, and stored within a GitHub repository. This requires more technical skills on the part of the teacher. The workflow for students to submit their work to you as the teacher will likely have a few more steps, as well.

Addressing the use of Jupyter Notebooks within Callysto and GitHub goes beyond the scope of this session.

Try Out a Notebook

Assuming that you have access to a Google account, either with a personal email address, or through your school or school board, jump in to the first Jupyter notebook that I authored for grade 9 students to work with:

Balancing Equations

If you are not logged in to a Google account, after following that link, you will be able to view but not save changes to the notebook. Be sure to sign in:

After signing in to a Google account, click the Changes will not be saved link:

... then choose Save a copy in Drive:

You may see a note from the Google Colab team describing recent changes to the Colab environment – you can dismiss this:

At this point you are ready to begin navigating the document.

Use the Table of Contents to move around within the document without a lot of scrolling:

The vertical yellow marker identifies what section of the document you have most recently navigated to.

This is a notebook designed for first use with students and coding in Grade 9 mathematics. By approaching a topic every student should have some familiarity with – solving equations – they can, at first, focus on the code they are writing:

Beginning with the Questions for you to try section, students are invited to write their own code, and balance equations independently:

Jupyter notebooks are a combination of text blocks and code blocks.

Code blocks must be run in order, from the top of a notebook to the bottom.

Jupyter notebooks, like R Studio documents, were designed to support reproducible data science.

[!NOTE]

As an aside regarding reproducible data science, here is an exemplar I made for the culminating project when I last taught MDM4U.

This heritage of support for reproducible data science in Jupyter notebooks allows students to make their process and thinking visible.

So... please take the time now to try out this first notebook.

If you'd prefer a more guided tour, here are a few short videos:

Additionally, please feel free to try out any of the notebooks included in the next section.

I will circulate to answer individual questions as they arise.

Additional Notebooks

Here are some other notebooks that you can open, duplicate, and try out now:

[!NOTE]

🚨 This document is quite long, representing far more content than would be approachable in a single class for most if not all students. Later in this session, we will learn how to "slice and dice" a Jupyter notebook in Google Colab to easily create a revised version with less content.

✏️ This document is not designed with a student audience in mind, but exists more as a set of examples for teachers to peruse and adapt as needed.

[!TIP]

Here is a folder in Google Drive containing all of the notebooks, and their related resources.

Mid-session Questions

The following questions came up during this session. As best as was possible, the questions and answers have been documented below. My thanks to Rob Gleeson for taking notes while questions were fielded during the session.

When we ran the code inside various code cells, starting in the middle of a Jupyter notebook and then running code within cells above and below the one we started with, we got inconsistent results. Why did that happen?
- Code blocks must be run once each, in sequence, much like pages in a novel must be read in order so that the narrative makes sense.
- When code blocks are run out of the order they are presented in, output will change.
- Be sure to run code blocks in order from top to bottom within a notebook.
  - Students new to coding will encounter this issue too.
  - When that occurs, it can be a good opportunity to discuss sequence as a key programming concept; this issue is connected to expectations within section C2 of the MTH1W curriculum.
- If you need to clear the output of code blocks to reset a notebook, choose the menu sequence: Runtime > Disconnect and delete runtime and then Edit > Clear all outputs.
I noticed that algebraic expressions are always simplified within the Balancing Equations notebook. Is there a way to turn that off?
- There are some limited ways to control whether expressions that involve a certain variable are simplified, but no straightforward way that I have found to disable simplification entirely.
- My current thoughts are to use the automatic simplification of expressions by the SymPy library as an opportunity to discuss the concept of equivalent algebraic expressions with students. This is a part of the Ontario curriculum for MTH1W (expectation C1.3).

Authoring Notebooks

The easiest way to get started with authoring a notebook is to make a copy of an existing notebook, and then modify it to suit your needs.

Here are a series of short videos explaining important concepts for authoring Jupyter notebooks:

Templates for Students

Referring to the PDF version of the curriculum for MTH1W, the term coding shows up 67 times. I will venture that the spirit of the new curriculum is to see coding become a another tool regularly used by students – not something that is "done" after one or two classes.

To that end, we can provide students with templates for common tasks, or develop such templates collaboratively with our classes – after organically looking at how coding helps us to explore a given mathematical concept.

After students become comfortable with using a Jupyter notebook in the Colab environment, they can reach for these templates as needed:

[!CONSIDER]

What other templates might be useful for us, as teachers, to create for our students to use?

Publishing Spreadsheets as a Data Source

When teaching students how to analyze one or two-variable data, it's ideal to make it as easy as possible for them to access that data.

One option is to publish the spreadsheet as a CSV file via the user interface within a Google Sheet.

Another option is to edit the spreadsheet URL directly.

Given a link to a spreadsheet, such as:

https://docs.google.com/spreadsheets/d/1E-iostgx4RiEajIu5DhVs-n6hXdQ1uPcLcWPFQc437s/edit?gid=0#gid=0

... replace:

/edit?gid=0#gid=0

... with:

/export?format=csv

... like this:

https://docs.google.com/spreadsheets/d/1E-iostgx4RiEajIu5DhVs-n6hXdQ1uPcLcWPFQc437s/export?format=csv

You can then load the contents of the spreadsheet into a dataframe in a Jupyter notebook, like this:

# Load the data from the spreadsheet
collected_data = pd.read_csv("https://docs.google.com/spreadsheets/d/1E-iostgx4RiEajIu5DhVs-n6hXdQ1uPcLcWPFQc437s/export?format=csv").dropna()

Try Authoring Your Own Notebook

Take one of the notebooks shared earlier, and try revising or extending it, or author your own from scratch.

I will circulate to help as needed.

Optionally, submit your completed notebook to this Google form. By doing so, you are giving permission for your notebook to be shared within this article and published under the license described earlier.

Publishing Workflow

If you are curious about how the materials for this session were published, that was the topic of the session I ran last year, in August 2023, at the CEMC Summer Conference for Computer Studies Educators.

Author Background

Before teaching, I worked in the software industry for four years as a developer and technical support specialist. After a year at OISE/UT, in 2006 I started teaching with a fall semester LTO at the now-closed Barton Secondary School in Hamilton, Ontario. To conclude that school year I completed a spring semester LTO at Erindale Secondary School in Mississauga.

In 2007 I was fortunate to earn a permanent position at North Park Secondary School in Brampton where the existence of the International Business and Technology Program allowed me to combine my background in technology with my love of teaching and learning. Across four years at North Park, I served for two years as the department head of the IBT program, taught a variety of mathematics classes, and grew computer science enrolment from 1 to 7 sections.

By 2011, my young family and I had moved to downtown Toronto. A desire to live in an urban environment without owning a car, some changes to hiring rules in public school boards, and the need to support my family without the uncertainty of work as a supply teacher, led me to pursue employment within independent schools. For three years, I worked at the Bishop Strachan School in a variety of roles as a teacher of mathematics and computer science and as a technology integrator. A move to Royal St. George's College in 2014 allowed for a new challenge – working within an all-boys environment after having taught at an all-girls school.

Toronto is a terrific city in many ways. By 2017, however, my family and I were ready for a change and, frankly, for a more affordable place to live. I am grateful to be a part of the community of teachers and learners at Lakefield College School, where I currently teach computer science to students across the gender spectrum and work with colleagues, where I can, to help advance pedagogy and the appropriate use of technology.

Building Computer Studies Classes for Student Agency

2020-08-20T22:30:32.000Z

No teacher knows quite what to expect in this coming school year.

What teachers do know is that the intrinsic motivation of our students is key to a positive outcome.

Whether we are learning in-person or remotely a student has a finite number of hours to dedicate to schoolwork.

And naturally we want computer studies to come first. 😇

How do we make that happen?

Student Agency

Writing software is a creative endeavour.

Since we teach computer studies it's a fair bet that we've all experienced that feeling of being "in the zone" while coding and the rush that comes when a goal is reached or a challenging problem solved.

In speaking with colleagues who teach visual art I've come to the conclusion that the emotional experience of writing software is not all that different from an artist working on a piece.

There is absolutely a place for specifications, one-size-fits-all assignments, and asking students to complete a defined task to learn a technique or evaluate a particular skillset.

If that is, however, the majority of a student's experience with our class – while their time with us may be occasionally interesting – it is unlikely to have felt terribly creative.

It must be our goal for students to finish our course feeling like an artist.

How many artists are told what to make?

Start With Conversations

What do your students do for fun?

Is it chess?

Drawing?

Going for a run?

What do your students worry about?

What problems do they want to solve in this world?

Facilitate a discussion about this.

Once students have warmed up to it, ask them write about their interests.

Use their responses as your guidebook to each student for their time in your course.

How often have you achieved a goal when writing a program and then immediately sought out your best friend, partner, or child to show them your brilliance?

How often have you been a bit disappointed when they didn't seem quite as impressed as they really honestly should be?

Students want to share what they've made.

If they can explain it with enough clarity that someone else might be able to at least appreciate the effort involved – then it's a fair bet that the student really understands what they've done¹.

It's our job to make that a regular part of class – something that students look forward to both as the person sharing or as the audience.

Have an extrovert on your hands? Let them share a success live in class.

Does a student worry about missing a detail or stumbling over words when speaking in front of others? Have them record a screencast demoing their work and explaining a key piece of logic.

Might someone not like how they sound on video? Ask them to write a blog post instead, and give other students the chance to read their work in advance of a class discussion.

Reserve time in each class for this exchange of ideas, with two or three students sharing each time you meet. Set up a regular schedule so students know when it's their turn.

This kind of conversation is not just for end products. It's a work in progress? Great! You're stuck with a syntax error or a logical error? No worries! Especially reinforce for your students that sharing challenges, and strategies employed in an attempt to solve the problem, are often more valuable fodder for discussion.

We want our students to feel like they are in cahoots together. That they can freely lean over, or speak up, and help someone else out.

Our students will be largely working toward their individual² goals in the course and it's that process of creation throughout the year, as much or more than the end product, that must form the bulk of evidence used to determine a student's final grade.

Since students are each working on a differentiated product, and they'll understand that they must be able to explain their work, we have everything to gain by encouraging a healthy collaborative environment in our classes.

Evaluate Mastery of Learning Goals

My second semester as a teacher was in the Mathematics department at Erindale Secondary School in Mississauga in the winter and spring of 2007.

I will never forget a meeting where the department head, John Flanagan, had one activity on the agenda: take a photocopy of the same student's responses for a unit test, take a copy of the solutions, go away and grade it, and then come back in twenty minutes to share and discuss the results.

Across the ten or so colleagues in that department we had a range of percentage grades for that test from 70% to 90%.

As a young teacher just starting out, that was an eye-opening experience.

Most teachers will, at least in private, acknowledge that numeric grades convey a false sense of precision.

Can you honestly tell someone the difference between a student who has earned 96% versus one who has earned 97% in your course at the end of the year?

Now can you do that for some subset of time and curriculum expectations?

Contrast that to a binary evaluation – yes or no – of whether a student has met an expectation. Most teachers feel comfortable with this.

Teacher: Can you decompose a problem and apply that in code?
Student: Sure I can – see here where I've used functions, and in this other program where I wrote a class – see, I reused that from an earlier program I wrote.
Teacher: OK, decomposing a problem... ✅

I grudgingly issue a percentage grade when required to for reporting deadlines at my school, but only after I've spoken to the student one-on-one, they've shown me their portfolio containing evidence of mastery for various learning goals, we've talked about what they've been able to cogently explain, and the student has made a proposal for what grade they feel they have earned. Far more often than not, students are realistic about where they stand.

Time Out

Right about now, you may be feeling like this is a nice picture being painted, but get real. This sounds like a tall order in a normal year. During a pandemic? That's madness.

Well, that's correct – we are in a pandemic.

Can you count on in-person instruction for this entire school year? No, of course not.

Any evaluation plan dependent upon seeing a student do something within a defined period of time in your class is a non-starter.

Any evaluation plan centred upon all of your students solving the same set of defined problems with the same expected output will be fraught with the kinds of challenges none of us became a teacher to spend time upon.

Perhaps you are a dogged personality and insist on trying to replicate the types of evaluation you've used for in-person learning with remote learning.

"In class or at home, I'll demand rigor by requiring all students to complete the same tasks on the same timeline."

I'd encourage you to consider whom that stance advantages and disadvantages. If your students are learning from home, do they all have equal access to a quiet space to learn? The same high-speed Internet? A reliable device? A parent who is not sick with COVID-19? What is it that your highly rigorous evaluation plan is evaluating? What a student knows or how much privilege they have? Do you really want to get into the privacy and ethics morass of testing-at-home software?

I'm painting a caricature, of course. I doubt that any teacher's thinking is so rigid.

If we are to have students:

make a decision, at the outset, about what they want to build in your course
gain the skills required to reach their goal
be able to explain concepts to others
build a portfolio of evidence differentiated from that of their peers
understand how they've progressed against a clear set of learning goals

... what does that look like, on a practical level?

Start at the Beginning

Not with "Hello world."

Especially early on in my career I made the mistake of overemphasizing programming skills.

Computer studies is far more than that. Says who? Says the Ontario curriculum.

What does effective computer studies learning look like?

It's not just programming. From page 4 of the The Ontario Curriculum, Grades 10 to 12, Computer Studies, 2008 (revised).

If we want a broad range of students to be engaged with computer studies, if we want to see greater enrolment from under-represented groups, we must be true to the curriculum.

Begin with the design cycle.

That student who loves chess? Help them arrange a video interview with a local chess club and find out what their members think a learn-to-play-chess app should include.

That student who loves to run? Set them up with athletes in a local running club to find out what functionality they'd like to see in their ideal intervals training app.

Maybe your students need a bit more structure – maybe they can't put their finger on a problem they want to solve.

In that case, consider speaking to an elementary teacher in your board. Younger students become the clients – your students are the developers. Use class time to set up video interviews between the two classes. Your students write educational games to the specifications of the elementary school students.

Your students cannot be their own audience.

They need to experience what it's like to speak with a potential end-user.

They need to know what they are shooting for when, inevitably, they get frustrated with syntax in your class, or you are tackling a particularly challenging coding concept.

When students know they have an authentic learning opportunity, I'm not exaggerating, it's like magic. They will find you to ask what can be done next. Project management becomes something students want to learn, because it's helping them achieve a goal they care about.

Use Source Control

Source control, and git in particular, have a questionable reputation for usability.

In truth, basic usage is not that hard. There is a graphical client. And GitHub has a lot of nice project management features built in.

You can explore the GitHub Education offering, or you can keep it simple:

students create a repository for each program they write
repositories are public³
commit frequently

With source control, you know exactly what code a student wrote and when.

Commit history for a student's culminating task

When a student commited code is clear. Coaching students to use descriptive commit messages is an ongoing task. Code changes can be seen by selecting the hash link (in blue) for a given commit.

Teachers know how a program is written – it's organic, bit by bit – and it most definitely doesn't happen with a single commit. Tracing the evolution of a student's work, from an academic honesty point of view, is straightforward⁴.

Use of GitHub means students can easily provide evidence for their portfolios – including specific line numbers of a given file.

Source control makes it a snap for students to identify and retreat from situations where their code has stopped working. Have a problem? Do a diff on your code to quickly see what's changed since the most recent commit. Can't figure it out? Revert state to your last commit and try again.

It's possible to write an entire series of articles on using source control in the classroom.

The short version is – basic usage is straightforward – and it's essential if you wish to differentiate your class and allow students to be specific when providing evidence of having met learning goals.

Use Portfolios

Artists create a portfolio of work, even as they learn. Students cannot apply to post-secondary programs in the arts without a portfolio.

Increasingly, summer employers in the technology sector want to see what a student has on their GitHub profile as evidence of what they can do.

Students looking to differentiate themselves from the pack in university applications can use their portfolio for that purpose, too.

When populating a portfolio becomes a regular part of your class (and it really needs to be a part of the daily process) students will learn the expectations. They tag evidence with the expectation they believe it fulfills. This becomes second nature. The onus is on students to show you what they know – it's not feasible for you, the teacher, to seek out evidence on your students' behalf.

Ideally you have access to a tool that makes this process sustainable.

That might be something fancy – a dedicated tool like Spaces or something similar.

Or it can be very basic. Last year, I had students maintain a Google Doc, submitted through Google Classroom, using a template I provided at the start of each portion of our course.

An excerpt from a student portfolio

A point form narrative with links to snippets of source code is maintained throughout the year and forms the basis of regular 1:1 meetings with students to discuss grades at reporting time.

Be the Guide at the Side, Not the Sage on the Stage

Class time is valuable.

In-person class time, this year, is precious.

Do you need to teach a specific concept? Explain a procedure?

Don't do that live to the whole class. Especially if you are teaching remotely.

Convey specific skills or concepts by video. Record your own if you have to, but work now to build a stable of resources you can refer students to.

Use synchronous class time, whether in-person or remote, for follow-up and discussion. For check-ins, for paired programming, for anything other than students listening to you talk at them.

Timelines for when a proportion of learning goals need to be met, or when specific learning goals need to be met, must be clear to students.

Big-picture thinking and identifying in advance what resources will help your students with each learning goal will form a large part of your planning.

However, for most of the year, you are unlikely to have a specific lesson plan for each class. Your students will be working on different things each time you meet. What have they worked on? That will be documented in their portfolio – remember, students maintain these in each and every class. How do you know that's happening? You're reviewing their edits as a part of your planning time. Use software that makes that sustainable.

Again, to be clear, we're absolutely not sitting back and reading Twitter while our students flail about.

In class, you must be present for consultation, guidance, direction to new resources, or a timely piece of small-group direct instruction. You may be familiar with just-in-time compilation. I tend to think of a differentiated classroom as just-in-time teaching. Despite our best efforts, most students retain very little from full-group instruction. Find that moment when a student is curious, or frustrated – and know what to say, or where to direct them – that's when the learning will stick.

Out of class, we corral useful materials. Provide asynchronous feedback. Record our own short, targeted videos. Build our own skillset. Reach out to parents – to share student successes – or, rarely in my experience – to talk about challenges you haven't been able to sort out through conversation with a student.

Spectrum of Possibilities

Much of what I've described probably sounds like project-based learning.

While I've served up a main course with my students on occasion, I've more often dished out dessert.

That's an honest statement about my past practice. I know where I'm headed, though.

It takes time to figure this out. You don't have to start in the deep end.

Douglas Kiang speaks about birdhouse projects. What's a birdhouse project? You know arts and crafts time at camp? Everyone is building the same birdhouse, but painting theirs in different colours than their peers? That's the idea, and it's honestly a great way to focus on a more specific subset of a curriculum. I'll take a course organized around birdhouse projects over one built on tests and one-size-fits-all assignments any day of the week.

What are some practical examples?

Talk with teachers in other subject areas. What are students learning in Physics class? Chemistry? Biology? Have your students earn credit in two courses at one time by building a program that models a concept from another subject area.

Generative art is a full of algorithms that contain a rich overlap between art, mathematics, and programming. Plotters bring generative art from the virtual realm to the physical.

Generative art can be animated:

Your browser does not support the video tag.

Generative art built by a student

This builds upon an algorithm outlined by Casey Reas that involves moving circles around a canvas based on when they are about to overlap. Opacity of lines is a function of the distance between the midpoints of circle. The hue of lines is controlled in part by the amplitude of the music being played.

Or static:

Making tees with photo-sensitive ink

From a past Grade 10 Introduction to Computer Studies class. Students demonstrate their understanding of sequence, selection, and iteration by making images that can be transferred to t-shirts using photosensitive ink.

Prioritize

Whatever you do with your students, this year, more than any other year, some things will fall by the wayside.

Don't stress about this.

Decide now what's an essential understanding.

Then be flexible.

Err on the side of being generous.

Assume best intentions.

What will students remember about your class?

Afford students even just a little bit of agency, and you'll never look back.

It certainly sounds like such a student will have demonstrated that they can convey meaning through various forms (see page 16). ^
Or group goals, in Grade 12 Computer Science. ^
Most of what you evaluate is a differentiated task that students document in their portfolio, right? There is no need for secrecy. Encourage a culture of students learning from one another. ^
Should that even become necessary. My experience is that when students are doing authentic, differentiated work, cheating becomes a non-issue. ^

A Planning Spreadsheet With A Curriculum Coverage Heat Map

2019-08-25T22:30:32.000Z

When planning out your course it’s helpful to be able to see what parts of the curriculum are well-covered and what parts may need more attention.

Department heads, school board representatives, or Ministry of Education inspectors will find a heat map like this useful, too.

If you populate a planning spreadsheet as described in this article, you will have a heat map like this:

Curriculum Coverage Heat Map

A point in time while planning out Grade 11 Functions. The heat maps makes it clear that financial applications needs a little attention.

Colour codes are as follows:

Color	Meaning
Red	No coverage
Yellow	Addressed once
Blue	Addressed twice
Light green	Addressed three times
Dark green	Addressed four times or greater

To generate the heat map, while planning out the sequence of your course, all that’s needed is to tag what you are doing in a lesson or activity with curriculum expectations.

For example, with Grade 11 Functions a few years ago, a colleague and I built the course in a spiralling progression, using many small “threads” and attempting to revisit larger curriculum topics more than once in a given year. To keep track of the learning occurring, we tagged our plans using curriculum expectations. See the Exp. columns at right below:

Using the Planning Spreadsheet for an Existing Course

If you happen to teach any of the following Ontario courses then you are in luck. I've already built versions of this planning spreadsheet against the expectations from each course below:

To use any of the spreadsheets above:

Follow the link; you will be prompted to make a copy of the spreadsheet in your own Google account.
Complete this one step so that links within your new copy of the spreadsheet connect to your own spreadsheet (and not the templates provided).

Adapting the Spreadsheet to Another Course

Adapting an existing spreadsheet like this to a new set of curriculum expectations is unquestionably a chore, but once it’s done, you can use it for a course over and over again, without having to go through this process.

Some tips:

Use the PDF version of a course curriculum for reference if you wish, but the text-only version for cutting and pasting.
To navigate within a text-only document, use Command-F and search for a passage of text.

To get started with adapting the planning spreadsheet to a new course, make a copy of the spreadsheet for any of the existing courses mentioned above.

Step One: Update Strands and Overall Expectations

This tab consolidates course strands and overall (major) expectations. It is used for reference and as a destination for hyperlinks from within the planning spreadsheet.

Open the curriculum documents for your course (see tips above) and begin cutting and pasting.

Colour coding for each row is managed automatically based on the contents of the Strand column.

Step Two: Update the Minor Expectations

This tab consolidates the minor expectations for a course. It is used for reference and as a destination for hyperlinks within the planning spreadsheet.

The Link Key and Link Value columns are used for generating automatic links from the Outline sheet when you tag lesson plans with relevant curriculum expectations.

There are several sub-steps required to build out this part of the spreadsheet.

Cut and paste the minor expectations within each overall (major) expectation from the ministry curriculum document.

As you go, be sure to retain accurate labeling/numbering of strand, major, and minor expectations. The Link Key field will then be automatically populated.

For example, say that you are looking at the first strand (A), from the first major expectation (1), and there are four minor expectations (1, 2, 3, 4). The progression would look like this:
Notice that the Major column contains hyperlinks. These connect back to the Overall Expectations sheet. The first major expectation is cell C2 on that sheet. The second major expectation is cell C3, and so on. Cut and paste and/or adjust formulas for the Major column cells following this pattern.
Finally, still on the Minor Expectations sheet, the Link Value column must be updated to refer to the current spreadsheet (rather than the originating spreadsheet from the template).

In the raw web site address from any cell in the Link Value column, identify the section noted here in red:

https://docs.google.com/spreadsheets/d/1byTg8V0vC1wvwpdw5x1-IWji8b3ku9fC3j7KwYkHgrc/edit#gid=663101658&range=C2

The precise letters and numbers of that section of the link will vary. Whatever they are for the spreadsheet you are working in, highlight them, and press Command-C to copy to your clipboard.

Perform a find and replace for that text (Command-Shift-H).

Replace that existing text with the characters in the same section of the address for your own copy of the spreadsheet:

Be sure to configure the find and replace operation as shown:

Step Three: Revise the Heat Map

Now it is time to modify the heat map to reflect the major and minor expectations of the course you are building the spreadsheet for.

Here is what the heat map looks like for MCR3U (the course this planning spreadsheet was originally built for in 2017-18):

Note that the non-coloured columns (C, E, G, I, et cetera) have been unhidden so that the underlying logic of this sheet can be explained.

There are several sub-steps involved to update this sheet, but they do not take too long to complete.

First, update the text for the strands (bold, larger text in the screenshot above) by copying and pasting from the Overall Expectations sheet that you have already modified.
Next, update the text for the major expectations that are part of each strand.
Now to adjust the core of the heat map – the colour coded cells.

Each colour coded cell is shaded based on the cell to its immediate right.

For example, consider expectation A1.1 in the MCR3U spreadsheet:

It is blue, because the cell to its right contains a 2.

The cell to the right contains a 2 because expectation A1.1 was tagged twice on the Outline sheet, meaning the expectation was addressed on two separate occasions throughout the year.

So how to update this part of the spreadsheet?

For each minor expectation, we need to update the link (on the colour-coded cell itself, B4 in the image above). We also need to update the formula that counts how many times that expectation was tagged (C4 in the image above).

For reference, open the Minor Expectations sheet in one browser window on your computer (if possible, it helps to work on a large monitor while doing this).

Keep a second browser window open on the Coverage Heat Map sheet.

Remember, there is one color coded cell for each minor expectation.

(If you need to add more cells for additional minor expectations, copy and paste from existing cells so that existing formulas and conditional formatting rules come along for the ride.)

First adjust hyperlinks for each color coded cell – in this example, we are linking to the minor expectation listed at cell C2 on the Minor Expectations sheet:

=HYPERLINK("#gid=663101658&range=C2","1")

Next, update the formula in the cell to the right, so that it counts occurrences of the correct curriculum expectation on the Outline sheet:

=COUNTIF(Outline!$H$2:$Q$100,"A1.1")

In this example, the formula looks for how many times expectation A1.1 was used as a tag for lessons.

So, after updating links and the formulas to count expectation tags – that should do it.

Of course, a bit of testing of your updated curriculum heat map is advisable.

As well, columns containing the white cells on the Coverage Heat Map sheet can be hidden, if desired.

Conclusion

My hope is that this article is helpful to other teachers.

If you do adapt this planning spreadsheet to another Ontario course, please let me know. I can add the course you've made a template for to the list provided above, allowing more teachers to benefit.

A Peculiar Form of Torment

2019-08-23T19:20:00.000Z

A possible future exchange on a popular TV game show:

I'll take Tedious Math Curricula for $200, Alex.
Answer: It's the Ontario mathematics course where half the expectations involve quadratic relations.
Question: What is Principles of Mathematics, Grade 10?

If you're a math teacher in Ontario, it's likely that at some point in your career, you've wondered whether your students – or you – could possibly make it through another day studying quadratics.

Another day of fitting curves to photos of a bridge:

Sipapu Natural Bridge

A stone bridge in central San Juan County, Utah, United States. Photo by Daniel Schwen, Wikimedia, with Desmos overlay by the author.

Or learning one more algebraic procedure to convert a relation in standard form:

y = a x^{2} + b x + c

...to its equivalent in vertex form:

y = a {(x - h)}^{2} + k

You might even struggle to make it through, who knows, dressing up some drab review of quadratic relations by using a Jeopardy! template at the end of a unit of study.

We are, of course, beholden to the curriculum, old and flawed though it may be.¹

At issue is that each of the tasks described above involve seat work where students primarily manipulate symbols on paper or on a computer. They are not particularly engaging or challenging. To boot, the Jeopardy! review activity introduces time pressure.

Given that we must work within a curriculum where the overemphasis on quadratics is a special form of torment for many students, what kind of tasks could we do instead?

What tasks might better activate the seven processes at the core of Ontario's math curriculum?

The Ball in a Can Challenge

In 2006 I had the opportunity to attend the Anja S. Greer Conference on Mathematics and Technology² at Phillips Exeter Academy for the first time.

Larry Ottman led a weeklong session focused on getting students up, moving, taking measurements, and testing hypotheses in math class.

With his permission (and his reminder that the task did not originate with him) I will describe the Ball in a Can Challenge here.

It says something about me, perhaps, that from Larry's weeklong session, I've only retained this one activity. It's a pretty good one, though, and just about the only task I can think of where the class often ends with a scene like this:

Your browser does not support the video tag.

Victory!

Students at Royal St. George's College celebrate.

As you see from the video – that's the task.

A ball bearing rolls from a ramp.

If the mathematics are sound, the ball lands in the can.

Simple, right? It can be. Let's dive in!

Apparatus

Here's what you need:

Building a Ramp

It takes some time to source materials and build the ramp, but after that initial investment, the activity is straightforward to set up in your classroom year after year. Diagram by Larry Ottman.

To build the ramp, use a couple of angle irons to join the lengths of 24-inch boards together. The boards are optimally just under an inch high and three inches wide:

A strong join between the boards is helpful to be certain they remain perpendicular.

Once that's done, attach an angle-iron to the end of each board.

The plastic corner molding, or quarter-round, is placed between the angle irons on the board ends. This creates the curve that the ball bearing will roll down:

The angle-iron should sit just a bit above the board, so that the corner-molding can be squeezed in at each end.

On the bottom of the ramp (the end the ball will fall from) attach a screw eye.

Use thread (or lightweight fishing line) and attach it to the screw eye.

Attach the magnet (or a weight) to the thread. Ensure that the thread is long enough such that the weight hovers just an inch or so above the ground. The thread length will need adjustment based on where you choose to place the ramp in your classroom. A couple of desks, carefully stacked on top of one another, can work, or a ladder. The higher you are able to safely place the ramp, the more fun the activity tends to be. Measure the length of the plumb line accordingly. You're aiming for something like this:

Here a weight borrowed from the Science department allows the plumb line to hang perpendicular to the floor.

You'll note that the end of the ramp in this most recent photo is constructed a little differently. The main idea is that, however the ramp is built, you want two boards that remain firmly perpendicular to one another. The ramp must allow for stable placement of the corner molding and for suspension of the plumb line directly under the location where the ball bearing leaves the ramp.

When you set up the ramp to begin the activity, it's a good idea to use a C-clamp to secure it to the ladder or desk:

It's no fun at all if students carefully take measurements, perform their calculations, prepare to do the final drop, and then someone accidentally bumps the ramp – requiring the entire process to begin anew.

Setting the stage

How to prepare students?

I've most often run the Ball in a Can Challenge as a consolidation activity in a unit of study.

A group of twelve works well, with students mostly partnered and assigned specific roles. This table is adapted from the original by Larry Ottman:

Role	Responsibilities	Number of students
Recorder	Writes down measurements, observes, makes suggestions. A quasi-leadership role.	One
Dropper	The person who actually drops the ball. Consistency of drop technique is important! 😅	One
Carbon paper	When the dropper is ready, this team tapes down a sheet of paper on the floor so that the ball is dropping into the middle of the paper. Then they lay the carbon sheet over top of the paper and when the ball is dropped, it leaves a mark on the paper. The dropper continues dropping until they are in enough of a rhythm that they consistently hit the same location on the paper (within a dime's diameter is sufficient). Once students have the spot, they should mark this on the paper. Another tip – it can be helpful to have the carbon paper team number the drops on the paper (1, 2, 3...) which can help the dropper become consistent more easily.	Two
Floor measurement	This team measures the co-ordinates of the point where the ball hits the floor. If you want, you can tell students that the floor represents the horizontal axis, but in my experience, they will arrive at this conclusion themselves after some valuable conversation.	Two
Vertex measurement	This team measures the co-ordinates of the vertex (where the ball leaves the ramp). You may wish to tell the team they are measuring "where the ball leaves the ramp" and leave it up to them to, again, decide amongst themselves that this represents the vertex, and that it's on the vertical axis of the mathematical model.	Two
Can height	This team measures the height of the can above the ground. Some good discussion typically ensues when students debate whether to measure from the top or the bottom of the can.	Two
Can placement	This team is responsible for placing the can prior to the penultimate drop.	Two

After measurements have been taken for the vertex and where the ball hits the ground, students can algebraically determine the missing value in the quadratic relation. I've had groups use both of these forms with success:

y = a {(x - h)}^{2} + k

Or:

y = a (x - r) (x - s)

It's a good conversation to hear students decide on which equation to work with, and how that connects to the physical apparatus of the task.

I encourage students to be clear about the meaning of the independent and dependent variables. What does x represent, and what are its units? And so on. This can be a nudge in the right direction if you've noticed the two measurement teams working with different units.

Finally, once students have the complete equation that describes the path of the ball bearing, it doesn't take long to decide how they can use the can's height above the ground, and what this implies for their next steps.

It's worth noting that this entire task can run in a far more free-form manner.

I've had students work in groups as small as four, assign roles independently, and meet with success.

Here's another photo:

Where is that ball landing?

After the dropper has become consistent, it's time to determine exactly where the ball is hitting the ground.

And another step in the process:

What's the height of that can?

Once students have a mathematical model to describe the flight of the ball bearing, they must determine the height of the can. What would the next step be?

Note that should your classroom be carpeted, you'll need a thin, firm board to place beneath the paper and carbon paper – otherwise the ball bearing will be too cushioned upon impact to allow the carbon paper to make a mark.

Assessment

I have sometimes assessed student work on this task, and sometimes run it simply as a consolidation activity before a major holiday during the school year.

The task is ripe for recording observations and conversations or assessing learning skills.

Recall the seven mathematical processes in Ontario mathematics instruction:

Problem Solving
Reasoning and Proving
Reflecting
Selecting Tools and Computational Strategies
Connecting
Representing
Communicating

The prompts given in this document can be helpful in guiding your students as they complete the Ball in a Can Challenge.

Before the task begins, I've sometimes told the class that later on, they'd each need to author a short reflection, answering these four questions:

Including a diagram, organize and explain the mathematics used by your group to obtain a successful result.
What went well in your group's effort to land the ball in the can?
What would you have changed about how your group completed the activity?
Evaluate your own participation in the group. What were your contributions? Were you an effective team member?

In some years, a day or two after the task itself, I've given a quiz or test question where a diagram is presented along with key measurements, and then each student must individually solve and explain the problem once more.

Final thoughts

The groups that are most successful are those that can communicate calmly and effectively with one another.

Don't permit students to work by trial and error, or "eyeball" measurements. This short-circuits the rich conversations that will ensue when a quantitative approach to problem solving is used.

It can be a real drag if a group doesn't land the ball bearing in the can on the first try.

With a small nudge to reconsider some part of their approach, I've never had a group fail to land the ball in the can on their second try.

Your browser does not support the video tag.

Success!

A small group of four students at Lakefield College School ace the challenge.

The Ball in a Can Challenge takes time to set up, but the payoff for your students will be worth it.

Nils Ahbel outlines this very well in Reflections on a 119-Year Old Curriculum. The content of his talk is well worth looking past the less than ideal audio quality of the recording. ^
The Greer conference at PEA deserves to be explicated in its own article. Here's the short version: if you're a math teacher, go. Find a way. You won't regret it. ^

Russell Gordon

Setting an App Icon

Keyboard Shortcuts in Playgrounds

Run Playground

Step Through My Code

Show or Hide Sidebar

Increase Text Size

Decrease Text Size

Select All Text

Re-Indent

Shift Right

Shift Left

Move to End of Current Line

Move to Start of Current Line

Select Entire Line

Block Comment

Ginger Molasses Cookies

Preamble

Preparation time

Yield

Equipment

Ingredients

Dry

Wet

Topping

Directions

Getting to Know Core Data

End Product

SwiftUI App Life Cycle and the Provided Template

Tip: Enable Core Data Debugging

Loading User Data at the Application Level

Decoding JSON Directly into Core Data Objects

Tip: Enable Concurrency Debugging

Using Background Threads and Loading User Images

Additional Resources

Creating a New Xcode Project for a SwiftUI App

Xcode 12

Xcode 11

Creating a Custom Theme Using Publish

Getting started

Duplicating the Foundation Theme

Adjusting Presentation Using CSS

Modifying Content Using Plot

Enabling Splash for Swift Syntax Highlighting

Conclusion

Core Data and Xcode Previews

Starting Point

Using Core Data Storage In-memory

Generating Sample Data

Providing a Single Instance of a Movie

Conclusion

Changing the Name of an App

Building an Animated Progress Meter View With SwiftUI

Goals

Showing progress toward a goal

Arranging the Views

Basic progress meter

Progress meter with a border

Eliminating Magic Constants

Using GeometryReader to Create an Adaptive Layout

Progress meter on a larger device

Creating a Colorful Progress Meter

Applying a gradient

An incorrect height

Oooh, so close!

The completed progress meter

Creating a Composable View

Conclusion

Adding a Physical Device as a Run Destination

Prevent the Dreaded Blue Screen of Death

Embiggen Text Like a Pro

Installing LargeType2

Configuring a Keyboard Shortcut

The Payoff

Snow Clearing and Computer Studies Enrolment

Context Over Tools

Build Community

Provide a Trial Run

Generating Physical Artwork Using Code

Positive Role Models