Welcome to CS Unplugged

Welcome to the documentation for the CS Unplugged project. The documentation is split into the following sections:

---

Getting Started Documentation

This documentation contains:

• Our expectations of your contributions to the project

• Steps to install the project on your system

• Explainations on how the project is setup

• Details on basic commands to use the system

---

Author Documentation

This documentation is for those who want to help write content for the CS Unplugged project, specifically text content. This is the documentation to read if you want to do any of the following (or similar):

• Add a new topic

• Clear up instructions on a lesson

• Add a language implementation for a programming challenge

• Add a translation

---

Developer Documentation

This documentation is for those who want to contribute to developing the Django system for delivering the CS Unplugged content. This is the documentation to read if you want to do any of the following (or similar):

• Edit HTML templates used to render webpages

• Edit CSS used for styling the website

• Add a generatable PDF resource

• Contribute to test suite for checking database models

• Alter URL routing for views

---

Getting Started

This documentation will help you understand how the project is setup, basic steps on how to use it, and our guidelines for your contributions.

Note

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please read our Code of Conduct before continuing. You can report unacceptable behaviour by emailing us.

Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language

• Being respectful of differing viewpoints and experiences

• Gracefully accepting constructive criticism

• Focusing on what is best for the community

• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances

• Trolling, insulting/derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others’ private information, such as a physical or electronic address, without explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at csse-education-research@canterbury.ac.nz. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4.

Contributing Guide

This page lists a set of guidelines for contributing to the project. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.

Reporting Issues and Making Suggestions

This section guides you through submitting an issue or making a suggestion for the CS Unplugged project. Following these guidelines helps maintainers and the community understand your findings.

Before Submitting an Issue

• Search the issue tracker for the issue/suggestion to see if it has already been logged. If it has, add a comment to the existing issue (even if the issue is closed) instead of opening a new one.

How do I Submit a Good Issue or Suggestion?

Issues are tracked in the GitHub issue tracker (if you’ve never used GitHub issues before, read this 10 minute guide to become a master). When creating an issue, explain the problem and include additional details to help maintainers understand or reproduce the problem:

For Reporting an Issue

• Use a clear and descriptive title for the issue to identify the problem.

• Clearly and concisely describe the issue and provide screenshots if required.

• Link any related existing issues.

If the issues is a code related issue, also include the following:

• Describe the exact steps which reproduce the problem in as many details as possible. For example, how you were generating a resource. When listing steps, don’t just say what you did, explain how you did it.

• Explain which behavior you expected to see instead and why.

• Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.

• Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.

• Include screenshots or animated GIFs if it helps explain the issue you encountered.

• What’s the name and version of the OS you’re using?

• What’s the name and version of the browser you’re using?

• If the problem is related to performance, please provide specifications of your computer.

For Making a Suggestion

Explain the suggestion and include additional details to help maintainers understand the changes:

• Use a clear and descriptive title for the issue to identify the suggestion.

• Clearly and concisely describe the suggestion and provide screenshots if required.

• Explain why this suggestion would be useful to most CS Unplugged users and isn’t something that should be a implemented as a community variant of the project.

• Link any related existing suggestions.

Note

Internal Staff Only: Assigning Issues

Our policy is to only assign a person to an issue when they are actively working on the issue. Please don’t assign yourself when you plan to do the task (for example: in the next few days), assign yourself when you begin work. This allows other team members to clearly see which tasks are available to be worked on.

Your First Code Contribution (pull request)

Unsure where to begin contributing to CS Unplugged? You can start by looking through the issue tracker.

Pull Requests

• Include a detailed explaination of the proposed change, including screenshots and animated GIFs in your pull request whenever possible.

• Read and apply the style guides listed below.

• Your pull request should be on a new branch from our develop branch, that is being requested to merge back into develop. The naming conventions of branches should be descriptive of the new addition/modification. Ideally they would specify their namespace as well, for example:

  • resource/puzzle-town

  • topic/algorithms

  • issue/234

• Link to any relevant existing issues/suggestions.

• Add necessary documentation (if appropriate).

We aim to keep the CS Unplugged project as robust as possible, so please do your best to ensure your changes won’t break anything!

Style and Etiquette Guides

Git

• Commits should be as descriptive as possible. Other developers (and even future you) will thank you for your forethought and verbosity for well documented commits. Generally:

  • Limit the first line to 72 characters or less

  • Reference issues and pull requests liberally

• We use Vincent Driessen’s Git Branching Model for managing development. Please read this document to understand our branching methods, and how to perform clear branches and merges.

  Specifically for our respository:

  • We create a new branch for each task of work, no matter how small it is.

  • We create the branch off the develop branch.

  • In general, the new branch should begin with issue/ followed by the issue number.

  • When a branch is completed, a pull request is created on GitHub for review.

  • Branches are merged back into develop.

GitHub

Note

Internal Staff Only

• Mention a user (using the @ symbol) when an issue is relevant to them.

• Only assign yourself to an issue, when you are actively working on it.

• The technical team may tag an author to review specific pull requests, and as a reviewer you can either approve, request changes, or just leave comments.

• A pull request requires one review approval to be merged.

• If multiple people are tagged as reviewers, we only need one review (unless otherwise specified). For example: For content changes, we ask that at least one member from each of the content and technical teams reviews the pull request.

• The creator of the pull request should assign all those suitable for review.

• The creator of the pull request is the only person who should merge the pull request. If you approve a pull request and it shows the big green button, please resist clicking it!

Project Structure

• Directories should be all lowercase with dashes for spaces.

• Directories and files should use full words when named, however JavaScript, CSS, and image directories can be named js/, css/, and img/ respectively.

Text (Markdown)

• Each sentence should be started on a newline (this greatly improves readability when comparing two states of a document).

Programming

Quote from Google style guides:

Be consistent.

If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

We aim to abide by the following style guides:

• Python - We follow PEP8 except for one change of line length. Django recommends allowing 119 characters, so we use this as our line length limit. This style is enforced by the flake8 style checker.

• HTML - We follow the open source HTML style guide by @mdo.

• CSS - We follow the open source CSS style guide by @mdo.

• JavaScript - We follow the Google JavaScript style guide.

Licencing

Any third-party libraries or packages used within this project should have their listed within the LICENCE-THIRD-PARTY file, with a full copy of the licence available within the third-party-licences directory.

Final Comments

After reading the sections above, you should be able to answer the following questions:

• When do I create a issue and how do I describe it?

• When and how do I create a new Git branch to work on?

• Internal staff only: When do I assign myself to an issue?

Installation Guide

This page will set your machine up for working on the CS Unplugged project. You should only need to do these installation steps once (unless the required steps for setup change).

Requirements

• At least 5 GB of hard drive space.

• An internet connection to download 1 to 2 GB of data.

Recommended Reading

If you aren’t familiar with the following systems, we recommend reading tutorials first on how to use them:

• Entering terminal commands for your operating system

• Git (here are two Git tutorials: one two)

Step 1: Setup Virtual Machine (optional)

For those working on a computer in a restricted environment (for example: a computer managed by an education insitution), then working in a virtual machine is recommended.

If you wish to setup a virtual machine for development, we have a guide here: Setting up a Virtual Machine.

Step 2: Install Git

Install the version control software Git onto your computer.

Note

If you are new to Git and not comfortable with using the terminal, you may like to use a free program like SourceTree to use Git.

Step 3: Create GitHub Account

If you don’t already have an account on GitHub, create a free account on the GitHub website. This account will be tied to any changes you submit to the project.

Step 4: Set Git Account Values

When you make a commit in Git (the term for changes to the project), the commit is tied to a name and email address. We need to set name and email address within the Git system installed on the machine.

• Setting your username in Git

• Setting your email in Git

You can also keep your email address private on GitHub if needed.

Note

If your GitHub account is secured with two-factor authentication (2FA) this is a perfect time to setup SSH keys.

Step 5: Download the CS Unplugged Repository

Firstly create the directory you wish to hold the CS Unplugged repository directory in if you wish to store the data in a specific location. Once you have decided upon the location, clone (the Git term for download) the project onto your computer.

If you are using terminal commands to use Git, type the following command in terminal (you don’t need to enter the $ character, this shows the start of your terminal prompt):

$ git clone https://github.com/uccser/cs-unplugged.git

Note

If you connect to GitHub through SSH, then type:

$ git clone git@github.com:uccser/cs-unplugged.git

Once Git has cloned the directory, checkout the repository to the development branch develop.

Step 6: Install Docker

We use a system called Docker to run the CS Unplugged system, both on local machine for development, and also when deployed to production. Download the latest version of the free Docker Community Edition for your operating system from the Docker Store.

Once you have installed the software, run the following commands in a terminal to check Docker is working as intended (you don’t need to enter the $ character, this shows the start of your terminal prompt).

$ docker version
$ docker compose version
$ docker run hello-world

Note

Depending on your operating system, if the above commands don’t work you may need to set Docker to be able to run without sudo. You will need to do this in order to use the dev helper script.

Step 7: Install Text Editor/IDE (optional)

This is a good time to install your preferred IDE or text editor, if you don’t have one already. Some free options we love:

• Atom

• Sublime Text

Step 8: Install Developer Tools (optional)

Note

You can skip this step if you’re only adding content to the project.

For those developing the CS Unplugged system, you will need to install some tools on your computer for local development. These tools include packages for style checking and compiling documentation.

Install Python 3

Install Python 3 with the following command in terminal:

$ sudo apt install python3

Install Python 3 PIP

Then install Python 3 pip (pip is a package management system used to install and manage software packages written in Python) with the following command in terminal:

$ sudo apt install python3-pip

Install Python virtualenv

We recommend (though it’s not required) to work within a virtual environment (see What is a Virtual Environment?). This helps to prevent conflicts with dependencies.

Install virtualenv with the following command in terminal:

$ sudo pip3 install virtualenv

Note

Optional step: You can also install virtualenvwrapper to make it easier when using and managing your virtual environments.

Create Virtual Environment

Type the following commands in terminal to create and activate a virtualenv named venv. You can change the virtual environment name to whatever you wish. You will need to replace the x with the version number of Python you have (for example: python3.5):

$ python -m virtualenv --python=python3.x venv
$ . venv/bin/activate

Note

If you installed virtualenvwrapper, then type the following command to to create a virtual environment called csunplugged, with Python within the virtual environment already set to Python 3.

$ mkvirtualenv --python=/usr/bin/python3.x csunplugged

You should now have the name of your virtual environment before the terminal prompt.

Install Packages into the Virtual Environemnt

Now that the virtual environment is active, we can install the Python packages into it for local development. This allows you to run these tools without having to run these within the Docker system.

$ pip install -r requirements/local.txt

Step 9: Check Project Setup Works

To check the project works, open a terminal in the project root directory, which is the cs-unplugged/ directory (should contain a file called dev).

Type the following commands into the terminal (we will cover these commands in more detail on the next page):

$ ./dev start
$ ./dev update

If this is the first time you’re running this script, it will need to build system images. This can take some time, roughly 15 to 30 minutes, depending on your computer and internet speed (we recommend grabbing a cup of tea and watching an episode of Brooklyn Nine-Nine on Netflix).

After the helper script builds the system images, it will automatically start the system, and will let you know when the system is ready. You should then be able to open your preferred web browser to the URL cs-unplugged.localhost and see the CS Unplugged homepage.

Congratulations if you made it this far and everything is working, you’re all set to contribute to the CS Unplugged project.

Project Structure

This page covers the structure of the CS Unplugged project. The following diagram will be helpful when reading the following sections:

├── csunplugged/
│   ├── build/
│   ├── config/
│   ├── general/
│   ├── gulpfile.js
│   ├── locale/
│   ├── manage.py
│   ├── package.json
│   ├── resources/
│   ├── static/
│   ├── temp/
│   ├── templates/
│   ├── topics/
│   └── utils/
├── docs/
├── LICENCE.md
├── README.md
├── requirements/
└── subtitles/

Repository Directory

The repository directory (or root directory) contains the following:

• csunplugged/

  • This directory contains the Django web system for the CS Unplugged website. This includes all raw text content, images, resources, etc.

• docs/

  • This directory contains the documentation for the repository (which includes the file you are reading now).

• infrastructure/

  • This directory contains Dockerfiles and helper scripts, used to setup the development and production environments for CS Unplugged.

• requirements/

  • This directory contains requirements files which outline Python dependencies required to run the project.

• subtitles/

  • This directory contains subtitle files for CS Unplugged videos.

• README.md

  • This file contains an introduction and important information for the repository.

• LICENCE.md

  • This file details the licences the repository uses.

• Plus other files used for installation and repository configuration.

csunplugged Directory

The csunplugged/ directory holds the Django web system and is split across the following directories:

• config/

  • This directory holds the settings used by the Django system. It’s unlikely you’ll edit the contents of this directory unless you are changing the Django configuration (for example: adding a new application).

Django contains ‘applications’ which are Python packages that provide some set of features. Each large part/chunk of the CS Unplugged is a separate application. The project currently contains the following applications:

• general/

  • This applicate displays webpages for generic pages on the website. For example: homepage, about page, contact page, etc.

• topics/

  • The core CS Unplugged content is split across topics, with each topic containing any combination of unit plans, lessons, follow up activities, programming challenges (plugged in activities), and much more. This application stores and displays the topics content.

• resources/

  • The CS Unplugged project contains custom printable resources that can contain randomly generated components and translations. This application stores, generates, and displays these resources.

Details on how to modify an application can be found within their relavent author and developer documentation pages.

The following directories are also required by the Django system:

• static/

  • This directory contains non-user-generated media assets (for example: images, JavaScript, CSS/SCSS, etc).

• templates/

  • This directory contains all the HTML templates for the Django system.

• locale/

  • This directory contains translations required for the Django system. Translations for topics/ are stored within the topics/content/.

The following directories are used when the server is running (for example: a script compiles the SCSS to CSS and saves it to the build/ directory for serving on a webpage). You should never save anything in these directories, as the contents are often overwritten and cleared.

• build/

  • Contains the generated output of the front-end script (for example: compiled and minified CSS and JavaScript, compressed images, etc).

• temp/

  • Contains temporary files used in creating generated files for build directory.

The csunplugged/ directory also contains the following files:

• manage.py

  • A file created by Django used to manage the Django web system. Don’t modify the contents of this file.

Helper Commands for Developing

Note

We assume by this point you have installed the project, checked the setup is working (see Step 9: Check Project Setup Works), and also have a basic understanding of the project structure.

The CS Unplugged project uses many systems (Django, Docker, Gulp, etc) to run, so we have written a script for running groups of commands for running the system while developing.

The script is called dev and can be found in the cs-unplugged folder of the repository. To run this script, open a terminal window in the directory and enter the following command (you don’t need to enter the $ character, this shows the start of your terminal prompt):

$ ./dev [COMMAND]

Where [COMMAND] is a word from the list below:

• build

• collect_static

• create_lesson_pdfs

• createsuperuser

• end

• exec

• help

• logs

• makemessages

• makemigrations

• make_resources

• make_resource_thumbnails

• migrate

• reboot_django

• rebuid_search_indexes

• restart

• start

• static

• style

• test_backwards

• test_coverage

• test_specific

• test_suite

• update

• updatedata

• update_static

All users of the project (content and technical developers) should become familiar with the following commands:

• start

• end

• build

• update

---

build

Running ./dev build will build or rebuild the Docker images that are required for the CS Unplugged system.

---

createsuperuser

Running ./dev createsuperuser runs the Django createsuperuser command to create a superuser account. This is required to access the Django admin interface.

---

collect_static

Running ./dev collect_static runs the Django collectstatic command to collect static files. It will copy files under the static/ folder into the staticfiles/ folder.

---

create_lesson_pdfs

Running ./dev create_lesson_pdfs runs the Django create_lesson_pdfs command. This will create PDF files for each lesson that are accessible through the website.

end

Running ./dev end will stop any containers which are currently running, this usually takes 10 to 20 seconds.

---

exec

Running ./dev exec [COMMAND] will run the given command in the Django Docker container. For example, to run ls in the Django Docker container, enter:

$ ./dev exec ls

help

Running ./dev help displays brief help text for the script. More details for each command can be found on this page.

---

logs

Running ./dev logs will display the logs for the running systems. The output is for all logs until the time the command was run, therefore successive calls may display new logs.

To follow logs as they output, enter docker compose logs --follow.

---

makemessages

Running ./dev makemessages runs the Django makemessages command. This will create message files where each message file represents a single language. Message files contain all available translation strings and how they should be represented in the given language.

---

makemigrations

Running ./dev makemigrations runs the Django makemigrations command to create migration files.

---

make_resources

Running ./dev make_resources runs the Django makeresources command. This will create resource files for each resource and puts them in build/resources/.

---

make_resource_thumbnails

Running ./dev make_resource_thumbnails runs the Django makeresourcethumbnails command. This will create thumbnail images for each resource and puts them in build/img/resources/{resource}/thumbnails/{language}.

---

migrate

Running ./dev migrate runs the Django migrate command to apply migration files.

---

reboot_django

Running ./dev reboot_django will rebuild the Django Docker container.

---

rebuid_search_indexes

Running ./dev rebuild_search_indexes runs the Django rebuild_search_indexes command. This will rebuild the search indexes for the website.

restart

Running ./dev restart is a shortcut for running:

• ./dev end

• ./dev start

More details for each command can be found on this page.

---

start

Running ./dev start starts the development environment. It performs the following tasks:

• Build system Docker images if required (see below)

• Start the Django website system

• Start the Nginx server to display the website and static files

• Start the database server

When you run this command for the first time on a computer it will also run ./dev build to build the system Docker images. This can take some time, roughly 15 to 30 minutes, depending on your computer and internet speed. Images are only required to be built once, unless the image specifications change (you can rebuild the images with ./dev build). Once the images are built, the script will run these images in containers.

Once the development environment is operational, run the ./dev update command to load the CS Unplugged content.

---

static

Running ./dev static runs the commands for generating the static files for the website.

If changes are made to the static files (for example, a new image is added) when the system is running, this command needs to be entered to view the new files on the website.

---

style

Running ./dev style will run the flake8 and pydocstyle commands to check the style of the project. If the output is 0 for a check, then there are zero errors.

---

test_backwards

Running ./dev test_backwards will run the test suite in reverse. This is useful to check if any tests are influencing the result of each other.

---

test_coverage

Running ./dev test_coverage will display a table detailing test code coverage, from the report generated by ./dev test.

---

test_specific

Running ./dev test_specific [MODULE_PATH] will run a specific test module. For example, running ./dev test_specific tests.resources.views.test_index_view will only run the tests for checking the index view of the resources application.

---

test_suite

Running ./dev test_suite will run the test suite, and create a report detailing test code coverage. The code coverage report can be displayed by running ./dev test_coverage.

---

update

Running ./dev update performs the following tasks:

• Update the database with the required structure (known as the schema)

• Load the CS Unplugged content into the database

• Create the required static files

Once the script has performed all these tasks, the script will let you know the website is ready. Open your preferred web browser to the URL cs-unplugged.localhost to view the website.

In more detail, ./dev update runs the Django makemigratations and migrate commands for updating the database schema, and then runs the custom updatedata command to load the topics content into the database. It also runs the static command to generate static files.

If changes are made to the topics content when the system is running, this command needs to be run to view the new changes on the website.

---

updatedata

Running ./dev update_data runs the custom update_data command to load the topics content into the database.

---

update_static

Running ./dev update_static runs ./dev static to build all the static files. Then runs the Django collectstatic command to copy all static files into the staticfiles directory.

---

You now know the basic commands for using the CS Unplugged system. You are now ready to tackle the documentation for the area you wish to contribute on. Head back to the documentation homepage and choose the documentation related to the task you wish to contribute to.

Author Documentation

The following pages are for those wanting to write or edit CS Unplugged content.

Writing Guide

The majority of our text content is written in Markdown, and we also developed a program called Verto to allow you to include HTML elements like images and videos with simple text tags.

For example, the following text:

# Scratch Programming Challenge

Try using the following blocks to create a program to display numbers 1, 2,
4, 8 and 16 on the screen, one at a time.


```scratch
when flag clicked

say [Hello] for [2] secs
```

Your program should look like the following:

{iframe link="http://scratch.mit.edu/projects/embed/148423714/?autostart=false"}

{panel type="note}
# Tips

- Make sure all your blocks are “snapped” together in a line like a
  jigsaw puzzle.

{panel end}

{button-link link="challenge/scratch-solution.html" text="Scratch Solution"}

will display as the following on the website:

Note

If you already know Markdown syntax, please remember the following project preferences (for consistency and readability):

• Use asterisks (*) for emphasis, instead of underscores.

• Use hyphens (-) for unordered lists.

• No HTML within text files, we use Verto text tags to add iframes, images, videos, etc.

Below is a basic guide to syntax for Markdown and Verto text tags. When viewing Verto documentation for a tag, the top of the page will detail how to use the tag in a basic example. Some text tags also have required and/or optional tag parameters for further configuration.

---

Blockquotes

> Blockquotes are very handy to emulate reply or output text.
> This line is part of the same quote.

Quote break.

> Oh, you can *put* **Markdown** into a blockquote.

---

Boxed Text (Verto feature)

Click here to read the documentation on how to box text.

---

Code

You are able to include code snippets, either in a line of text or as a new block.

To include inline code, add a backtick to either side of the code. For example: `print(“Hi”)` will display as print("Hi"). You cannot set the language syntax highlighting for inline code.

To create a code block, use a line of three backticks before and after the code. You also can add syntax highlighting by specifying the language after the first set of backticks (list of language codes).

```python3
def find_high_score(scores):
    if len(scores) == 0:
        print("No high score, table is empty")
        return -1
    else:
        highest_so_far = scores[0]
        for score in scores[1:]:
            if score > highest_so_far:
                highest_so_far = score
        return highest_so_far
```

def find_high_score(scores):
    if len(scores) == 0:
        print("No high score, table is empty")
        return -1
    else:
        highest_so_far = scores[0]
        for score in scores[1:]:
            if score > highest_so_far:
                highest_so_far = score
        return highest_so_far

---

Comment (Verto feature)

Click here to read the documentation on how to add a comment.

---

Conditional (Verto feature)

Click here to read the documentation on how to define a conditional.

---

Embed iframe (Verto feature)

Click here to read the documentation on how to embed with an iframe.

---

Emphasis

Emphasis, aka italics, with *asterisks*.

Strong emphasis, aka bold, with **asterisks**.

Emphasis, aka italics, with asterisks.

Strong emphasis, aka bold, with asterisks.

Note

We do not use underscores for emphasis to maintain consistency and readability.

---

Glossary Link (Verto feature)

Click here to read the documentation on how to define a glossary link.

The list of defined glossary terms available for linking to can be found in the Application Structure Configuration File.

---

Heading (Verto feature)

Click here to read the documentation on how to create a heading.

---

Image (Verto feature)

Click here to read the documentation on how to include an image.

---

Interactive (Verto feature)

Click here to read the documentation on how to include an interactive.

---

Line Breaks

Here are some things to try out:

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a
*separate paragraph*.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line
in the *same paragraph*.

---

Links

There are several links that may be used:

The general syntax for links is [link text](link url) where link text is the text to be displayed in the document, and link url is the destination of the link.

Escaping closing brackets within link URLs: A closing bracket can be escaped by prefixing it with a backslash \).

Link to page within website

Note

This type of link requires knowledge of project URL routing, required URL values, and the Django URL template tag. If you are unsure on how to create a link of this type, please contact us and we will be happy to help.

Links to pages within the website use the Django url template tag. In order to create a link, use the values that would be given to the template tag. See the example below for an example.

This following Markdown:

See [challenge 4.1]('topics:programming_challenge' 'kidbots' 'check-if-divisor').

results in the following HTML:

See <a href="/en/topics/kidbots/programming/check-if-divisor">challenge 4.1</a>.

Currently linking to a heading within the page is not supported (or recommended as heading text can change easily).

Link to resource page with pre-selected options

Note

This type of link requires knowledge of project URL routing, required URL values, and the Django URL template tag. If you are unsure on how to create a link of this type, please contact us and we will be happy to help.

This link uses the same syntax as internal links, with a query string appended at the end. The Markdown processor Verto will read the link string and seperate everything before and after the ? symbol, and will create a link using the Django URL tag with everything before the symbol (the same way a normal internal link is created). Then the processor will append the query string at the end of the link (see example below). Each parameter should be a resource option with its desired value. Values given as query parameters override the default values for each resource.

This following Markdown:

[Little Red Riding Hood cards]('resources:resource' 'sorting-network-cards'?type=riding_hood)

results in the following HTML to the Django system:

<a href="{% url 'resources:resource' 'sorting-network-cards' %}?type=riding_hood">Little Red Riding Hood cards</a>

results in the following HTML to the user:

<a href="/en/resources/sorting-network-cards/?type=riding_hood">Little Red Riding Hood cards</a>

Link to a page outside of website (external link)

These are links to websites that are not a part of the CS Unplugged project. The URL should include the https:// or http:// as required.

Check out [Google's website](https://www.google.com).

Create a link on an image (Verto feature)

Images should now be linked using the caption-link and source tag parameters for including an image.

Create a link on a button (Verto feature)

Click here to read the documentation on how to add a button link.

---

Lists

Lists can be created by starting each line with a - for unordered lists or 1. for ordered lists. The list needs to be followed by a blank line, however it doesn’t require a blank line before unless the preceding text is a heading (a blank line is then required). If you are having issues with a list not rendering correctly, try adding a blank line before the list if there is none, otherwise submit a bug report if you are still having rendering issues.

Unordered list:
- Item 1
- Item 2
- Item 3

Ordered list:
1. Item 1
2. Item 2
3. Item 3

Unordered list:

• Item 1

• Item 2

• Item 3

Ordered list:

1. Item 1

2. Item 2

3. Item 3

Nested lists can be created by indenting each level by 2 spaces.

1. Item 1
  1. A corollary to the above item, indented by 2 spaces.
  2. Yet another point to consider.
2. Item 2
  * A corollary that does not need to be ordered.
    * This is indented four spaces, because it's two for each level.
    * You might want to consider making a new list by now.
3. Item 3

1. Item 1

1. A corollary to the above item, indented by 2 spaces.

2. Yet another point to consider.

2. Item 2

• A corollary that does not need to be ordered.

  • This is indented four spaces, because it’s two for each level.

  • You might want to consider making a new list by now.

3. Item 3

---

Math

To include math (either inline or as a block) use the following syntax while using LaTeX syntax.

This is inline math: ``\( 2 + 2 = 4 \)``

This is block math:

``\[ \begin{bmatrix} s & 0 \\ 0 & s \\ \end{bmatrix} \]``

Math equations are rendered in MathJax using the LaTeX syntax.

---

Panel (Verto feature)

Click here to read the documentation on how to create a panel.

Supported panel types

These are the panel types that have built in styling for CS Unplugged. Other panel types are supported, but will not have any special styling. Have a play around with them to see how they look!

• ct-algorithm

• ct-abstraction

• ct-decomposition

• ct-pattern

• ct-logic

• ct-evaluation

• video

---

Scratch (Verto feature)

Click here to read the documentation on how to include an image of Scratch block.

---

Table of Contents (Verto feature)

Click here to read the documentation on how to include a table of contents.

---

Tables

Tables can be created using the following syntax:

Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

The outer pipes (|) are optional, and you don’t need to make the raw Markdown line up prettily, but there must be at least 3 dashes separating each header cell. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

Markdown	Less	Pretty
Still	renders	nicely
1	2	3

---

Video (Verto feature)

Click here to read the documentation on how to include a video.

---

Writing Philosophy

This page covers the philosophy of writing material for CS Unplugged.

Most of the philosophy of what we mean by the “Unplugged” approach is on our website (On the ‘About’ page under ‘Principles’).

In terms of how we present material, Unplugged activities are formatted as Lesson plans that have enough detail for a classroom to use, including links to computational thinking. If you have an idea for an activity, but it’s not quite fleshed out enough as a lesson plan, it can be contributed as a PDF file to the Community section, which is an area where we collect great ideas that can inspire teachers and lesson plan authors.

Understanding Configuration Files

There is a lot of content within the CS Unplugged project. We split this content across many files and configuration files are the things that bring everything together. These files are used for configuring the content data stored in the system database, so it is important to understand how to read and write these configuration files if you are working on this project.

Here is an example configuration file used to define follow up activities in the CS Unplugged project:

binary-number-bracelets:
  number: 1
  md-file: bracelets.md
  curriculum-areas:
    - arts
    - design

hidden-binary-signals:
  number: 2
  md-file: hidden-binary-signals.md
  curriculum-areas:
    - listening

This page aims to give a brief tutorial on YAML files, so you can modify and write configuration files within this project.

YAML files are mostly made up of key/value pairs, where each key is matched with one value. This is often called a dictionary in programming languages. This configuration file contains the follow three key/value pairs:

• The key learning-outcomes points to the file learning-outcomes.yaml

• The key programming-challenges-structure points to the file programming-challenges-structure.yaml

• The key topic-structure-files points to the ordered list of files binary-numbers/structure.yaml and error-detection-and-correction/structure.yaml

The majority of configuration files within this project only use dictionaries (sets of key/value pairs) and lists to store their data. Here are some other useful tips:

# You can include comments in YAML by starting with a # character

# This stores the integer 7 in the key 'number'
number: 7

# This is an ordered list of dictionaries within the key 'difficulties'
difficulties:
  - level: 1
    name: Beginner
  - level: 2
    name: Growing Experience
  - level: 3
    name: Ready to Expand

You may find that there is more than one configuration file that you need to modify/create. This is because it is difficult to read files using deep nesting (indentation), so we have split configuration data across multiple files to avoid this issue.

If you want to learn more about YAML, there are plenty of great tutorials available online.

Topic Content

The topics application (see What is an Application?) is the main focus of the CS Unplugged website, as it contains the majority of educational material for the project.

Topics Overview

The following diagram shows the general structure of the topics application.

• The application is made up of topics.

  • A topic must contain at least one unit plan.

    • A unit plan must contain at least one lesson.

      • A lesson can contain learning outcomes, and generated resources.

  • A topic can also contain curriculum integrations.

    • A curriculum integration can also contain curriculum areas.

  • A topic can also contain programming challenges.

    • A programming challenge can use different programming languages, and be set at a specific difficulty.

• Programming challenges, learning outcomes, curriculum areas, and glossary definitions, are defined at a language level (e.g. English or German, not programming language), so can be used by all topics within that language directory.

This is a broad overview of the topics application, and the following sections provide more details.

Viewing All Topics Content

When developing locally, once you have run ./dev start and ./dev update (see Helper Commands for Developing) you can go to the url below to see your local version of the website:

cs-unplugged.localhost/

Topics Content Directory

The content directory for the topics application contains:

• A directory for each language in which content exists, named using the Django locale code. These language directories each contain:

  • A folder for each Topic, containing the content Markdown files.

  • YAML files containing strings that need to be translated in each different language folder.

• A structure directory which contains all configuration YAML files.

• Several auto-generated directories. Please ignore these.

Content Files

There are 3 different types of files used for adding content to CS Unplugged:

• Content Markdown files

• YAML files containing translatable strings

• YAML configuration files

All of these files live inside the topics/content directory. The first two types of files are unique for each language, and are stored in a directory tree specific to that language. This directory is named using the languages Django locale code eg. en, de_AT. The YAML configuration files are shared amongst all languages, because the content structure is the same for all languages. These files live under a special structure directory.

As a simple rule, structure files situated inside the structure directory contain no text a website user will see. Any user facing text lives in either a Markdown file or a YAML translation file inside the locale specific directories.

Adding Content

Note

If you are adding content for a language other than english then wherever the directory path topics/content/en/ is used, replace en/ with the relevant folder for that language, e.g. de/

The following flow charts will take you step by step through the process of adding new content to the topics application. Below this section are full details on how to structure and write the configuration files for the topics application. These charts and descriptions will use “Binary” as an example topic.

Adding a Topic

To set up a new topic, which you can then add content to, you will first need to:

• Create a set of required directories and Markdown files within the topics/content/en/ directory (replace en/ if you are creating content for a different language, e.g. de/).

• Add the required headings to these files.

• Create a set of required directories and config files within the topics/structure/ directory.

• Add the minimum required configuration settings to these files.

Before you can run ./dev update and view the topic on your local machine, these Markdown and YAML files must contain some required headings and content. We recommend adding some placeholder content to these files and checking that you can view them locally, before moving on to adding content.

After these steps have been completed you can run ./dev update, and view the topic at:

cs-unplugged.localhost/en/topics/

To create the required directories and Markdown files follow this flow chart:

Add the following content to these Markdown files:

• An H1 heading (i.e. has a single # prefix) and some placeholder text to the topic description Markdown file.

  • For example, add # Binary to the top of the file and the placeholder text test underneath this.

• An H1 heading and placeholder text to the unit-plan Markdown file.

• An H1 heading and placeholder text to the lesson Markdown file.

To create the required directories and config files follow this flow chart:

Add the required fields, and their keys, to these YAML files:

• The topic config file. The required fields are listed in the Topic Configuration File section.

• The unit-plan config file. The required fields are listed in the Unit Plan Configuration File section.

• The lesson config file. The required fields are listed in the section Lesson Configuration File section.

Now you can run the ./dev update command. Once this has finished you will be able to view the topic at cs-unplugged.localhost/en/topics/

The description of the topic is written in the topic Markdown file. This file:

• Is in: the topic directory, e.g. the description file for Binary will be in topics/content/en/binary/.

• Is called: <topic-key>.md where <topic-key> is the key (What is a Key?) of the topic and the name of the directory it is in, e.g. binary.md or kidbots.md.

• Contains: an H1 heading (i.e. has a single # prefix) and the content of the description.

Note

The heading written in this file will be used exactly as it is given throughout the website as the name of the topic.

Warning

Every topic needs at least one unit plan, therefore the system will not allow a topic to be loaded until a unit plan is connected to it.

Adding a Unit Plan

The Markdown file containing the content of the unit plan:

• Is in: the unit plan directory, e.g. the unit plan file for Binary Unit Plan 2 will be in topics/content/en/binary/unit-plan-2/.

• Is called: <unit-plan-key>.md where <unit-plan-key> is the key (What is a Key?) of the unit plan and the name of the directory it is in, e.g. unit-plan-2.md.

• Contains: an H1 heading (i.e. has a single # prefix) and the content of the unit plan.

Note

The heading written in this file will be used exactly as it is given throughout the website as the name of the unit plan.

Warning

Every unit plan needs at least one lesson, so the system will not allow a unit plan to be loaded until a lesson is connected to it.

Adding a Lesson

The Markdown file containing the content for the lesson:

• Is in: the lesson subdirectory in the unit plan directory, e.g. topics/content/en/binary/unit-plan/lessons/.

• Is called: <lesson-key>.md where <lesson-key> is the key (What is a Key?) of the lesson, e.g. introduction-to-binary.md.

• Contains: an H1 heading (i.e. has a single # prefix) and the content for the lesson.

Note

The heading written in this file will be used exactly as it is given throughout the website as the name of the lesson.

Note

If a lesson includes programming challenges, Computational Thinking links, and/or learning outcomes, then the corresponding configuration and content files may also need to be added or updated.

Adding Learning Outcomes

There are two types of YAML files for Learning Outcomes. One is in topics/structure and is shared by all language folders. The other is the translation YAML file, which is unique to a language and is in topics/content/<language> (e.g. content/en)

There should only be one learning-outcomes.yaml file per language directory. If one already exists in the language directory then add new learning outcomes to this, rather than creating a new file.

The translation YAML file containing learning outcomes descriptions:

• Is in: topics/content/en

• Is called: learning-outcomes.yaml

• Contains: Descriptions of all learning outcomes. Every learning outcome key present in the Learning Outcomes Configuration File must be present in the English translation file.

  For example,

  binary-convert-decimal:
    text: Perform a demonstration of how the binary number system works by converting any decimal number into a binary number.
  binary-justify-zeros-and-ones:
    text: Justify why there aren’t actual 0’s and 1’s zooming around inside a computer.
  binary-argue-zeros-and-ones-stored:
    text: Argue that 0’s and 1’s are still a correct way to explain what is stored in the computer.
  

You will now be able to add learning outcomes to lessons and programming challenges by referencing the keys you specified in the learning outcomes configuration file.

Note

If a learning outcome contains curriculum areas, then the curriculum areas configuration file may also need to be added or updated.

Adding Curriculum Areas

There should only be one curriculum-areas.yaml file per language directory. If one already exists in the language directory then add new curriculum areas to this, rather than creating a new file.

The translation YAML file containing curriculum areas descriptions:

• Is in: topics/content/en

• Is called: curriculum-areas.yaml

• Contains: Descriptions of all curriculum areas. Every curriculum area key present in the Curriculum Areas Configuration File must be present in the English translation file.

  For example,

  computational-thinking:
    name: Computational Thinking
  algorithmic-thinking:
    name: Algorithmic Thinking
  decomposition:
    name: Decomposition
  

You will now be able to add curriculum areas to learning outcomes and curriculum integrations by referencing the keys you specified in the curriculum areas configuration file. Only curriculum areas without any children can be added to items.

Adding a Programming Challenge

There should only be one .yaml file per language directory. If one already exists in the language directory then add new programming challenges to this, rather than creating a new file.

You will now be able to add programming challenges to lessons by referencing the keys you specified in the programming challenges configuration file.

A programming challenge is split into several different sections, each of which is an its own Markdown file, all of which are in topics/content/en/binary/programming-challenges/<challenge-key>/ where <challenge-key> refers to the key (What is a Key?) of the challenge, e.g. count-to-16.

1. The challenge description:

• Is called: <challenge-key>.md where <challenge-key> is the key of the challenge, e.g. count-to-16.md.

• Contains: an H1 heading (i.e. has a single # prefix) and the content of the challenge.

Note

The heading written in this file will be used exactly as it is given throughout the website as the name of the programming challenge.

2. The expected output

• Is called: <language>-expected.md where <language> is the key of the programming language, e.g. python-expected.md.

• Contains: The expected output for the programming challenge, e.g. an embedded Scratch program or Python output.

3. Hints (optional)

• Is called: <language>-hints.md where <language> is the key of the programming language, e.g. scratch-hints.md.

• Contains: Hints for how to complete the challenge, e.g. suggested Scratch blocks.

4. Example solution(s)

• Is called: <language>-solution.md where <language> is the key of the programming language, e.g. ruby-solution.md.

• Contains: Example solutions to the challenge, e.g. Scratch program.

5. Extra challenge(s) (optional)

• Is called: the value defined in the programming challenges configuration file. A common filename is extra-challenge.md.

• Contains: Content for an extra challenge.

2-4 from the list above can be given in multiple programming languages. Therefore, the languages you have chosen must be specified in the programming-challenges.yaml configuration file, as well as the programming-challenges-structure.yaml configuration file.

Note

If the challenge includes learning outcomes, then the corresponding configuration file will also need to be added or updated to include new learning outcomes.

Adding a Curriculum Integration

There should only be one .yaml file per language directory. If one already exists in the language directory then add new curriculum integrations to this, rather than creating a new file.

The Markdown file containing the content of the curriculum integration:

• Is in: the curriculum integration directrory, e.g. curriculum integrations in Binary will be in topics/content/en/binary/curriculum-integrations/.

• Is called: <integration-key>.md where <integration-key> is the key (What is a Key?) of the curriculum integration, e.g. whose-cake-is-it.md.

• Contains: an H1 heading (i.e. has a single # prefix) and the content of the integration.

Note

If the integration includes curriculum areas and/or prerequisite lessons, then the corresponding configuration and content files will also need to be added.

Adding Glossary Definitions

There should only be one glossary directory per language directory. If one already exists in the language directory then add new definitions to this, rather than creating a new directory.

Each glossary definition requires a Markdown file within the glossary folder, with the filename as the glossary key. When linking text to a glossary definition, the key is used as the identifier. For example, with the key pixel, then a file pixel.md is expected.

Each Markdown file should start with a heading containing the glossary term (this should be capitalized and include any required punctuation), followed by the term’s definition.

Continuing the pixel.md example from above, this could be the possible contents of that file.

# Pixel

This term is an abbreviation of picture element, the name given to the
tiny squares that make up a grid that is used to represent images on a
computer.

Adding a Classroom Resource

There should only be one classroom-resources.yaml file per language directory. If one already exists in the language directory then add new resources to this, rather than creating a new file.

The translation YAML file containing classroom resource descriptions:

• Is in: topics/content/en

• Is called: classroom-resources.yaml

• Contains: Descriptions of all classroom resources. Every classroom resource key present in the Classroom Resources Configuration File must be present in the English translation file. Descriptions must be short (less than 100 characters), as this list is displayed on the lesson sidebar. If a longer description is required, this should be within the lesson text within a panel.

  For example,

  pens:
    description:  Pens
  paper:
    description:  Paper
  number-line-0-20:
    description:  Number line from 0 to 20
  

Adding an Age Group

There should only be one age-groups.yaml file per language directory. If one already exists in the language directory then add new age groups to this, rather than creating a new file.

The translation YAML file containing age group descriptions:

• Is in: topics/content/en

• Is called: age-groups.yaml

• Contains: Optional descriptions of programming challenge defined in the Age Group Configuration File .

  For example,

  5-7:
    description: Description of the 5-7 age group.
  

Adding a Programming Challenge Difficulty

There should only be one programming-challenges-structure-difficulties.yaml file per language directory. If one already exists in the language directory then add new difficulties to this, rather than creating a new file.

The translation YAML file containing difficulty descriptions:

• Is in: topics/content/en

• Is called: programming-challenges-structure-difficulties.yaml

• Contains: Descriptions of difficulties defined in the Programming Challenges Structure Configuration File. Every difficulty key present in the configuration file must also be present in the English YAML translation file.

  For example,

  difficulty-0:
    name: Try it out
  difficulty-1:
    name: Beginner
  difficulty-2:
    name: Growing experience
  

Adding Programming Challenge Languages

There should only be one programming-challenges-structure-languages.yaml file per language directory. If one already exists in the language directory then add new languages to this, rather than creating a new file.

The translation YAML file containing programming language descriptions:

• Is in: topics/content/en

• Is called: programming-challenges-structure-languages.yaml

• Contains: Names of languages defined in the Programming Challenges Structure Configuration File. Every language key present in the configuration file must also be present in the English YAML translation file.

  For example,

  scratch:
    name: Scratch
  python:
    name: Python
  

Configuration Files

This section details configuration files within the content/structure directory. These files are in YAML format. If you are not familiar with YAML, see Understanding Configuration Files.

The diagram below shows an example of YAML file locations for the content/structure/ language directory, where:

• Blue is directories.

• Red is YAML configuration files.

├── age-groups.yaml
├── binary-numbers
│   ├── binary-numbers.yaml
│   ├── curriculum-integrations
│   │   └── curriculum-integrations.yaml
│   ├── programming-challenges
│   │   └── programming-challenges.yaml
│   └── unit-plan
│       ├── unit-plan.yaml
│       └── lessons
│           └── lessons.yaml
├── classroom-resources.yaml
├── curriculum-areas.yaml
├── error-detection-correction
│   ├── error-detection-correction.yaml
│   ├── curriculum-integrations
│   │   └── curriculum-integrations.yaml
│   └── unit-plan
│       └── unit-plan.yaml
├── learning-outcomes.yaml
├── programming-challenges-structure.yaml
└── structure.yaml

In the following sections, each configuration file is explained in more detail.

Note

• Some of the keys (What is a Key?) have angle brackets around them, <like so>. This means that they are variables and you can call them whatever you like in your configuration file (without the angle brackets).

Application Structure Configuration File

• File Name: structure.yaml

• Location: topics/content/structure/

• Purpose: Defines the top level configuration files to process for defining the content of the topics application.

• Required Fields:

  • topics: A list of file paths to topic configuration files.

• Optional Fields:

  • age-groups: The path to the age group configuration file.

  • classroom-resources: The path to the classroom resources configuration file.

  • curriculum-areas: The path to the curriculum areas configuration file.

  • glossary-folder: The folder name that contains the Markdown files for glossary definitions.

  • learning-outcomes: The path to the learning outcomes configuration file.

  • programming-challenges-structure: The path to the programming exercises structure configuration file.

A complete application structure file may look like the following:

topics:
  - binary-numbers
  - error-detection-correction

age-groups: age-groups.yaml
learning-outcomes: learning-outcomes.yaml
curriculum-areas: curriculum-areas.yaml
programming-challenges-structure: programming-challenges-structure.yaml

glossary-folder: glossary

Topic Configuration File

• File Name: <topic-key>.yaml

• Location: topic/content/structure/<topic-key>/

• Referenced In: topic/content/structure/structure.yaml

• Purpose: This file defines the attributes of a specific topic, including connected unit plan, programming challenge, and curriculum integration configuration files.

• Required Fields:

  • unit-plans: A list of keys, where each key is a unit plan.

• Optional Fields:

  • icon: An image file to be used as the icon for the topic.

  • other-resources: A Markdown file containing information about other related (external) resources.

  • programming-challenges: The path to the programming challenges configuration file.

  • curriculum-integrations: The path to the curriculum integrations configuration file.

A complete topic structure file may look like the following:

unit-plans:
  - unit-plan
  - unit-plan-2

icon: img/binary-numbers-0-1.png

other-resources: other-resources.md

programming-challenges: programming-challenges/programming-challenges.yaml
curriculum-integrations: curriculum-integrations/curriculum-integrations.yaml

Unit Plan Configuration File

• File Name: <unit-plan-key>.yaml

• Location: topic/content/structure/<topic-key>/<unit-plan-key>/

• Referenced In: topic/content/structure/<topic-key>/<topic-key>.yaml

• Purpose: This file defines which lessons to use in each age group

  • Required Fields:

    • lessons: The path to the lessons configuration file.

    • age-groups: Keys of age groups and their corresponding lessons.

      • Required Fields:

        • <age-group>: The key for the age group.

          • Required Fields:

            • <lesson-key> The key for a lesson.

              • Required Fields:

                • number The number order for this lesson, relative to this age group. This value allows a lesson to be used in different age groups, as different numbered lessons (e.g. lesson 2 for 5 to 7, but lesson 1 for 8 to 10).

  • Optional Fields:

    • computational-thinking-links: The Markdown filename containing

      Computational Thinking links.

A complete unit plan structure file with multiple lessons may look like the following:

lessons: lessons/lessons.yaml

age-groups:
  5-7:
    what-is-binary-junior:
      number: 1
    how-binary-digits-work:
      number: 2
  8-10:
    how-binary-digits-work:
      number: 1
    reinforcing-sequencing-in-binary-number-systems:
      number: 2
    codes-for-letters-using-binary-representation:
      number: 3

Lesson Configuration File

• File Name: <lessons>.yaml

• Location: topic/content/structure/<topic-key>/<unit-plan-key>/lessons/

• Referenced In: topic/content/structure/<topic-key>/<unit-plan-key>/<unit-plan-key>.yaml

• Purpose: This file defines all the lessons (and their respective attributes) for the specific unit plan.

  • Required Fields:

    • <lesson-key>: This is the key for the lesson. Each lesson has its own list of required and optional fields:

      • Optional Fields:

        • duration: The estimated time to complete the lesson (in minutes).

        • computational-thinking-links: The Markdown filename containing Computational Thinking links.

        • programming-challenges: A list of keys corresponding to programming challenges.

        • programming-challenges-description: The Markdown filename containing a description for the programming challenges.

        • learning-outcomes: A list of keys corresponding to learning outcomes.

        • classroom-resources: A list of keys corresponding to classroom resources.

        • generated-resources: A list of keys of generated CSU resources connected to this lesson.

A complete lesson structure file with multiple lessons may look like the following:

introduction-to-bits:
  programming-challenges:
    - count-to-16
    - count-to-1-million
  learning-outcomes:
    - binary-data-representation
  generated-resources:
    - sorting-network
  classroom-resources:
    - pens
    - paper
    - dice

how-binary-digits-work:
  computational-thinking-links: how-binary-digits-work-ct-links.md
  learning-outcomes:
    - binary-data-representation
    - binary-justify-representation

Age Group Configuration File

• File Name: age-groups.yaml

• Location: topics/content/structure/

• Referenced In: topics/content/structure/structure.yaml

• Purpose: Defines the age groups available for all lessons.

• Required Fields:

  • <age-group-key>: This is the key for the age group. Each age group has its own list of required and optional fields:

    • Required Fields:

      • min_age: The minimum age of the age group.

      • max_age: The maximum age of the age group.

A complete age group structure file may look like the following:

5-7:
    min_age: 5
    max_age: 7
8-10:
    min_age: 8
    max_age: 10
11-14:
    min_age: 11
    max_age: 14

Age group descriptions can then be set by creating a YAML translation file topics/content/en/age-groups.yaml.

For example,

5-7:
  description: Description of the 5-7 age group.

Learning Outcomes Configuration File

• File Name: learning-outcomes.yaml

• Location: topics/content/structure/

• Referenced In: topics/content/structure/structure.yaml

• Purpose: Defines the learning outcomes available for all topics.

• Required Fields:

  • <learning-outcome-key>: This is the key for the learning outcome. Each learning outcome has its own list of required and optional fields:

    • Optional Fields:

      • curriculum-areas: A list of curriculum area keys (see example file below). Each curriculum area listed must not contain child curriculum areas.

A complete learning outcome structure file may look like the following:

no-physical-zeros-ones:
  curriculum-areas:
    - computational-thinking

binary-correct-representation:
  curriculum-areas:
    - computational-thinking
    - data-representation

maths-comparing-numbers:
  curriculum-areas:
    - numeracy

Curriculum Areas Configuration File

• File Name: curriculum-areas.yaml

• Location: topics/content/structure/

• Referenced In: topics/content/structure/structure.yaml

• Purpose: Defines the curriculum areas available for all topics.

• Required Fields:

  • <curriculum-area-name>: This is the key for the curriculum area. Each curriculum area has its own list of required and optional fields:

    • Required Fields:

      • number: A number used for ordering curriculum areas. Areas are sorted in ascending numbers (smallest to largest).

      • colour: The CSS colour class to use for colouring the curriculum area badge on the website. This colour is also applied to all children of curriculum area.

        Available colours include:

        • blue

        • green

        • light-purple

        • orange

        • pink

        • purple

        • red

        • teal

        • yellow

        These colours are defined in: csunplugged/static/scss/website.scss.

    • Optional Fields:

      • children: A list of sub-curriculum areas (see example file below). Children inherit the same colour and number as their parent.

An example curriculum areas file with multiple curriculums may look like the following:

maths:
  colour: green
  children:
    - geometry
    - algebra

science:
  colour: blue

art:
  colour: teal

Note

The maximum depth for children is one, that is, children curriculum areas cannot have children.

Note

When including a curriculum area in another configuration file, only curriculum areas with no children can be listed. This is because it can be confusing when items belong to the parent curriculum area but not any child in particular. Therefore each item must be linked to a curriculum area with no children. Parent curriculum areas (areas with children) are used in search forms to select all child curriculum areas and their related items.

Programming Challenges Structure Configuration File

• File Name: programming-challenges-structure.yaml

• Location: topics/content/structure/

• Referenced In: topics/content/structure/structure.yaml

• Purpose: This file defines the structure of programming challenges for all topics.

• Required Fields:

  • languages: A list of languages that programming challenges can be given in.

    • Required Fields:

      • <language-name>: This is the key for the language. Each language has its own list of required and optional fields:

        • Required Fields:

          • number: A number used for ordering programming languages. Languages are sorted in ascending numbers (smallest to largest).

        • Optional Fields:

          • icon: An image file to be used as the icon for the language.

  • difficulties: A list of difficulty keys programming challenges can be labelled with, from easiest to hardest.

Warning

Due to technical limitations, the programming challenge difficulty keys must not be purely numeric. For example, the key difficulty-1 is valid, but the key 1 is not.

A complete programming challenge structure file may look like the following:

language:
  scratch:
    number: 1
    icon: img/scratch-cat.png
  ruby:
    number: 2

difficulties:
  - difficulty-1
  - difficulty-2
  - difficulty-3

Programming Challenges Configuration File

• File Name: programming-challenges.yaml

• Location: topics/content/structure/<topic-key>/programming-challenges/

• Referenced In: topics/content/structure/<topic-key>/<topic-key>.yaml

• Purpose: This file defines the programming challenges (and their respective attributes) for a particular topic.

• Required Fields:

  • <programming-challenge-name>

    • Required Fields:

      • challenge-set-number: The group of related programming challenges this challenge belongs to (see note below).

      • challenge-number: The number order for this programming challenge (see note below).

      • difficulty-level: A key corresponding to a difficulty level.

      • programming-languages: A list of keys corresponding to programming languages that this challenge is given in.

    • Optional Fields:

      • learning-outcomes: A list of keys corresponding to learning outcomes.

      • extra-challenge: A Markdown filename containing the content for an extra challenge.

Note

Programming challenges are sorted by their challenge-set-number and then their challenge-number. These numbers are not directly displayed, but used to calculate a programming challenge’s number for a lesson.

For example, if a lesson lists the following challenges:

• Challenge A: 1.1

• Challenge B: 1.3

• Challenge C: 2.2

• Challenge D: 9.3

The lesson will display these challenges as:

• Challenge A: 1.1

• Challenge B: 1.2

• Challenge C: 2.1

• Challenge D: 3.1

A complete programming challenges structure file may look like the following:

count-to-16:
  challenge-set-number: 1
  challenge-number: 1
  difficulty-level: 1
  programming-languages:
    - ruby
    - python
  learning-outcomes:
    - programming-sequence

count-to-a-million:
  challenge-set-number: 1
  challenge-number: 2
  difficulty-level: 3
  programming-languages:
    - python
  learning-outcomes:
    - programming-basic-logic
  extra-challenge: extra-challenge.md

Curriculum Integrations Configuration File

• File Name: curriculum-intergrations.yaml

• Location: topics/content/structure/<topic-key>/curriculum-integrations/

• Referenced In: topics/content/structure/<topic-key>.yaml

• Purpose: Contains a list of curriculum integrations that can be used to integrate the topic with another area in the curriculum.

• Required Fields:

  • <curriculum-integration>: This is the key for the curriculum integration. Each curriculum integration has its own list of required and optional fields:

    • Required Fields:

      • number: The number order for this curriculum integration. Curriculum integrations are sorted by this number.

      • curriculum-areas: A list of keys corresponding to other curriculum areas that this curriculum integration could be used in. Each curriculum area listed must not contain child curriculum areas.

    • Optional Fields:

      • prerequisite-lessons: A list of lesson slugs that are expected to be completed before attempting this curriculum integration.

        • Required Fields:

          • <lesson-key> A key corresponding to a lesson in the given unit plan.

A complete curriculum integration structure file with multiple curriculum integrations may look like the following:

binary-number-bracelets:
  number: 1
  curriculum-areas:
    - math
    - art
  prerequisite-lessons:
    unit-plan:
      - introduction-to-binary-digits
    unit-plan-2:
      - counting-in-binary

binary-leap-frog:
  number: 2
  curriculum-areas:
    - math
    - pe
  prerequisite-lessons:
    unit-plan-2:
      - counting-in-binary

Classroom Resources Configuration File

• File Name: classroom-resources.yaml

• Location: topics/content/structure/

• Referenced In: topics/content/structure/<topic-key>/<unit-plan-key>/lessons/lessons.yaml

• Purpose: Defines the classroom resources available for all topics.

• Required Fields:

  • classroom-resources: List of available classroom resource keys

A complete classroom resources structure file may look like the following:

classroom-resources:
  - pens
  - paper
  - number-line-0-20
  - musical-instruments
  - alphabet-cards
  - parity-cards-set
  - whiteboard
  - whiteboard-pens
  - product-barcodes
  - payment-system
  - pencils
  - stopwatch
  - handheld-whiteboards
  - clipboards
  - blocks
  - hula-hoop
  - counters
  - chalk
  - colouring-pens

Content Style Guide

Writing Style

When using pronouns in reference to a hypothetical person, gender neutral pronouns (they/their/them) should be used.

All documents (other than those for internal use only) must be written clearly and simply so that a non-expert is able to understand them. Preferably documents should be readable by students.

Any jargon used needs to be clearly explained and should be considered as a glossary definition.

Capitalisation Rules

In the majority of cases capitalisation should not be used for keywords and titles, with the following exceptions, where the phrase refers to a commonly used term that is often capitilised in the literature:

• Computer Science.

• Computational Thinking.

• Digital Technologies (note that this is the correct form to refer to the subject area in NZ, with caps and plural; if it’s referring to something other than the subject then use lower case e.g. “smartphones and other digital technologies”, or even better, avoid the phrase e.g. “smartphones and other digital devices”).

• Sorting Network.

• Numeracy.

• Literacy.

The following wouldn’t be capitalised: binary number(s), digits, binary digits

Extra notes for specific content

Glossary

The following are added to the glossary and linked to where the words are used:

• All Computer Science, programming, and Computational Thinking jargon.

• All education jargon.

• All curriculum language that is not broadly used internationally.

Topic

Topic description must apply to all the units within the topic. It is one introductory paragraph, less than 150 words, which gives a big picture overview of why this topic is being taught/is relevant, and what it will cover.

Learning outcomes

Learning outcomes are written using language familiar to teachers and simple enough that it is understandable for students. Learning outcomes always begin with a verb.

Programming challenges

There needs to be enough scaffolding to support students to be able to achieve a result, independently.

When listing Scratch block:

1. Separate out all the blocks that “click” together, leaving all the information inside where the parameter is written. All duplicates of a block should be displayed.

2. Where a variable is inserted into another block, those blocks stay together, example below:

   

3. All join blocks are displayed as one and all the variables/text are included, example below:

   

4. For blocks containing join blocks keep the join block within the parent block, example below.

   

5. Loops should keep the condition blocks, but the blocks within the loop should be extracted.

Translations

Getting Started

It’s really easy to start contributing translations using CS Unplugged

1. Read this documentation page, especially the Translation Notes section.

2. Create an account on Crowdin.

3. Visit the CS Unplugged Crowdin page.

4. Start translating!

Note

The in-context translation has been removed temporarily as translation infrastructure is being updated. We aim to re-add this feature in a future update.

Crowdin Overview

We use a localisation management platform called Crowdin for translation of CS Unplugged. Our project is public, meaning that anyone can create an account and contribute translations.

Crowdin has excellent documentation for translators, and all translators should read the following documents:

• Crowdin Introduction, which provides an overview of the Crowdin platform

• Online Editor, which explains how to use the Crowdin UI to contribute translations.

Translation Phases

There are 3 phases translation phases used to ensure high quality translation of CS Unplugged content:

1. Translation

2. Proofread

3. Technical Review

In the inital translation phase, anyone (who has created an account with Crowdin) can contribute translations. These translations are then reviewed by a designated proofreader who will check the translations for accuracy and consistency. To request to become a proofreader, please contact one of the Crowdin project managers.

Note

While not enforced by Crowdin, proofreaders should not approve their own translations. Instead, they should be reviewed by a different proofreader.

Finally, a technical review will be performed by a member of the CS Unplugged technical team. In this review, technical components such as Verto tags and document structure will be checked.

Translation notes

Note

On Crowdin, Markdown files are translated on a per-sentence basis. There may be some cases where this is not desirable, and some paragraph level restructuring is required to convey a concept in a given language.

In these cases, it could be possible to work around this with tricks such as

• translating one sentence into the translation box for another.

• translating a sentence into a blank string.

These techniques are highly discouraged as they fight against many aspects of the Crowdin system including

• QA checks that ensure translations match the structure of the source strings.

• Translation memory.

• In context localisation.

• Special Verto tags which are within curly braces { } should not be translated, except for text after alt in an image tag. For example the text:

  {image file-path="img/topics/binary-cards.png" alt="Diagram showing 2 binary cards"}
  

  The only text to translate is ‘Diagram showing 2 binary cards’.

• Text within Scratch tags should be translated using Scratchblocks syntax.

If you are unsure how to translate a line, please leave it for another translator.

Developer Documentation

The following pages are for those wanting to develop the CS Unplugged system.

Developer Philosophy

We follow the following philosophy for developing the CS Unplugged project:

We aim to create software that enables authors to easily create, modify, and share education material for the CS Unplugged project.

In short: Think of the author.

This page explains design decisions we made throughout developing the CS Unplugged system.

Configuration Files

We use YAML for storing configuration data of content. It has improved human readability over JSON and XML, especially for authors who have no or little experience with configuration files.

We try to avoid deep nesting (indentation) within configuration files as it’s harder for authors to read nested data. We have split configuration data across multiple configuration files to avoid this issue.

Writing Content

We chose Markdown as the language for text content as it has a great balance between simplicity of writing for authors, and clear structure when converting to HTML.

Django Setup

This page covers the configuration of Django for this project.

Django Overview

We aim to create and clear Django system for ease of development. We are using some advised patterns and practices from Two Scoops of Django - Best Practices for Django 1.8, which include (but is not limited to the following):

• Locking versions of dependencies.

• Django secret settings are loaded from environment variables.

• All templates are located in the templates/ directory.

• The base Django directory, containing settings.py and base urls.py is called config/.

The Django system currently contains the following applications:

• general/ - For general website pages (for example: home, about, etc).

• topics/ - For topics content (for example: lessons, follow up activities, programming challenges, etc).

• resources/ - For translatable PDF resources with random elements.

Database Structure

The following image shows the relationships between models across all applications within the database.

Note

Lesson and Programming Challenge Language Implementation models have the parent’s Topic saved directly within their model.

The rest of the Developer Documentation will inform you of how to develop the applications and other components of the CS Unplugged project.

Loaders

To populate the database with content we have written a series of custom loaders. The loaders for an application are found in the management/commands/ directory, and there is approximately one loader for each configuration file.

Besides populating fields in the database, a loader is also responsible for checking that its corresponding configuration file contains all the required fields, Markdown files are not empty, and icons can be found. If any of these conditions are not met, then an error is thrown.

Errors are defined in utils/errors/ and should aim to be as descriptive and useful as possible as they will most often be read by an author and not necessarily a Python developer.

Website Design (HTML templates/CSS)

This page covers the HTML templates and CSS styling used for the CS Unplugged website.

Warning

The current design of the website is a work in progress.

Expect everything to change.

In summary:

• We plan to use Bootstrap 4 for the underlying framework for responsive design.

• We use SCSS for style sheets where possible.

• We wrap translatable strings in {% trans %} or {% blocktrans trimmed %} tags.

• We use the django-bootstrap-breadcrumbs package for breadcrumbs on the website.

  • This requires templates to inherit from the template one level up on the breadcrumb track in order for breadcrumbs to be calculated correctly.

  • This also requires specific objects in the context to be named the same as parents in the breadcrumb chain. For example: the associated topic is always saved in the template context as topic.

  • For complete examples of the breadcrumb package being used, look at the templates for the topics application.

Setting Custom Converter Templates

We use Verto to convert Markdown files to HTML. To override a default Verto template, add a new HTML file to utils/custom_converter_templates/<processor-name>.html.

The template file name must correspond to the name of a processor in Verto (for example: image.html, or the name of a supporting template specified in Verto documentation (for example: relative-image-link.html). A list of the available processors is available in the Verto Documentation.

General Application

The general application manages and serves basic pages for the CS Unplugged website, including (but not limited to):

• Homepage

• About page

• Contact Us page

The general application uses a model to store pages that are available for searching. More information about why this application has both data in configuration files and in view/url files can be found in the Search Feature documentation.

Searchable General Pages Configuration File

• File Name: general-pages.yaml

• Location: general/content/

• Purpose: Defines general pages that should be available for searching.

• Required Fields:

  • <general-page-slug>: This is the slug for the general page. Each general page has a list of required fields:

    • Required Fields:

      • name: The name of the page.

      Note

      Text values are stored within this file (and not separate language files) as the names are only used for the English site. The retrieval of names will be need to be established for internationalisation of the search feature (see #798). This could be accomplished by parsing template and using TranslatableModel.

      • template: Filename of template to parse text values from.

      • url-name: Name of page URL (as specified in the general’s URL routing file).

Topics Application

The topics application is the main focus of the CS Unplugged website, as it contains the majority of educational material for the project.

Note

This guide assumes you’ve read the following documentation:

• Topic Content - Provides detail on content in topics application

• Django Setup - Provides detail of database structure

In general the topics application is a standard Django application, however it does store and update it’s associated data for it’s models uniquely.

Instead of creating and updating model objects through the website (for example: edited by an online editor), the objects are updated by a management script. The content for the topics application is stored within the contents/ directory, as is run for each deployment of the system. Storing the content within the Git repository gives us greater control on reviewing and accepted proposed changes to content.

The management command for updating the applications data is loadtopics (which is automatically called when running updatedata), and can be found at management/commands/loadtopics.py.

Classic Application

The classic application stores data related to Classic CS Unplugged, are provides redirections to the website for old links and also allows old pages to be available in the website search.

The classic application uses a model to store pages that are available for searching. More information about why this application has both data in configuration files and in view/url files can be found in the Search Feature documentation.

Searchable Classic Pages Configuration File

• File Name: classic-pages.yaml

• Location: classic/content/

• Purpose: Defines classic pages that should be available for searching.

• Required Fields:

  • <classic-page-slug>: This is the slug for the classic page. Each classic page has the following required field:

    • Required Field:

      • name: The name of the page.

      Note

      Text values are stored within this file (and not separate language files) because the Classic CS Unplugged website can only guarantee English content. These results should not be displayed for other languages.

Media

Warning

The documentation for this page is still being written.

This page will cover:

• Animations - GIF conversion using the SWF > MP4 > GIF conversion pipeline

• Images

• Video

Animations

Animations are located in the csunplugged/static/img directory.

Animations are currently created by creating the elements using Adobe Illustrator and then animated on Adobe Animate. The frame rate used is normally 30fps, but this does not need to be strictly followed. The animations are then exported in a .gif format.

The SWF > MP4 > GIF Pipeline

Sometimes, exporting as a .gif file will not work on Adobe Animate (exports with incorrect colours, or incomplete animations). In this case, the animation must follow the rather convuluted SWF > MP4 > GIF pipeline.

1. The animation is exported in a .swf format in Adobe Animate.

2. The animation is converted to a .mp4 file using a conversion tool, such as Swivel.

3. The animation is converted to a .gif file using a conversion tool, such as ezgif.

Resources Application

Warning

The documentation for this page is still being written. This page will also cover:

• Structure of resource application and model.

• Creating new resources.

Resource Specification

Each resource requires the following:

• Definition in YAML file.

• Markdown file containing name/description.

• Python module for creating the resource pages.

• Thumbnail image.

Each of these are explained in further detail below. We recommend looking at existing resources to get a clearer picture of how new resources should look.

YAML file definition

Each resource is defined in the YAML file located at: csunplugged/resources/content/structure/resources.yaml.

Each resource requires the following:

• <resource-key>: This is the key for the resource.

• generator-module: Python module for generating resource, relative from csunplugged/resources/generators/ (for example: SortingNetworkResourceGenerator).

• thumbnail-static-path: Thumbnail image for the resource, relative from csunplugged/static/ (for example: img/resources/sorting-network/thumbnail.png).

• copies: Boolean if the resource should allow multiple copies. If each resource is exactly the same, then the value should be set to false.)

Markdown file

Every resource must have a markdown file containing the name and description of the resource. This will be parsed by Verto, and must begin with a top level heading which will be used as the resource name. This file must be named <resource-key>.md and located in csunplugged/resources/content/en.

Python module

The Python module defined in the YAML file must contain a class inheriting from resources.utils.BaseResourceGenerator. The Python class must have the same name as the module.

The generator class must contain the following method definition:

data(self)

Create one copy of the resource.

Return type

A dictionary or list of dictionaries for each resource page.

Each dictionary must contain the following keys/value pairs:

• type: Page type (either image or html) as a string.

• data: If type is html, then a HTML string is expected. If type is image, a Pillow Image object is expected.

If a list of dictionaries is provided (when a resource has more than one page), one of the dictionaries must have the key thumbnail set to True. This is used to determine which page is used to create the resource thumbnails.

If specific user options are required for resource generation, the generator class can implement a function get_additional_options(self) which must return a dictionary mapping an option identifier to a ResourceParameter instance. For example, a resource subclass may implement the following:

@classmethod
def get_additional_options(cls):
    """Additional options for BinaryCardsSmallResourceGenerator."""
    return {
        "number_bits": EnumResourceParameter(
            name="number_bits",
            description=_("Number of Bits"),
            values= {
                "4": _("Four (1 to 8)"),
                "8": _("Eight (1 to 128)"),
                "12": _("Twelve (1 to 2048)")
            },
            default="4"
        ),
        "dot_counts": BoolResourceParameter(
            name="dot_counts",
            description=_("Display Dot Counts"),
            default=True,
        ),

The following ResourceParameter subclasses are available:

• EnumResourceParameter - One from a set of predefined values

• BoolResourceParameter - True/False values

• TextResourceParameter - Freeform text value

• IntegerResourceParameter - Integer value

Each ResourceParameter class has configurable options which are documented on in the class docstring. We recommend looking at existing resources to see how the various ResourceParameter classes can be used.

If get_additional_options is implemented, the subtitle property method should be overridden. The method should display the additional options and also call the parent’s subtitle result:

Note

The subtitle method should be declared as a property with @property and only have one parameter self.

subtitle(self)

Return the subtitle string of the resource.

Used after the resource name in the filename, and also on the resource image.

Return type

Text for subtitle (str).

For example, a resource with options display_numbers and black_back might implement the following subtitle method

@property
def subtitle(self):
    """Return the subtitle string of the resource.

    Used after the resource name in the filename, and
    also on the resource image.

    Returns:
        Text for subtitle (str).
    """
    if self.requested_options["display_numbers"]:
        display_numbers_text = "with numbers"
    else:
        display_numbers_text = "without numbers"

    if self.requested_options["black_back"]:
        black_back_text = "with black back"
    else:
        black_back_text = "without black back"

    text = "{} - {} - {}".format(
        display_numbers_text,
        black_back_text,
        super().subtitle
    )
    return text

If copies are required for the resource, COPIES = True should be added as a class constant on the subclass.

If custom thumbnails are to be displayed for each resource combination, the save_thumbnail method can be overridden.

Thumbnail image

This image should represent the resource, and be at least 350px high.

Dynamic Text Overlay

In many cases, resources comprise of a base PNG image with text dynamically overlayed from within the python view, based on a users request. Cases where this is necessary include:

• Randomly generated numbers or data.

• Text, which must be translated into the user’s language.

While the actual text is added dynamically, the layout/colour/font/size of that text on the resource should be determined as part of the design process. To achieve this, we have developed a pipeline to allow designers to define these text fields in Adobe Illustrator, and export them in an SVG format. This information can then be used to dynamically render the required text as closely as possible to the intended design. This process is outlined in more detail below, for both developers and designers.

For Designers

The following workflow has been designed for Adobe Illustrator. Currently, other graphics software is not supported.

Setting up the document

1. Create a new layer called TEXT (Anything on this layer will be ignored during the export to PNG).

Creating a new dynamic text field

1. Create a new transparent rectangular text box in the TEXT layer.

2. Add sample text.

3. Set font, font size and colour.

4. Position and rotate text box as required.

5. Expand text box to define the area in which the text will be allowed.

6. Give the text box element a unique identifier.

   • This is achieved by expanding the TEXT layer in the layers panel, and double-clicking on the text box element.

   • The identifier must be unique across all layers.

Notes:

• Sample text must be added - do not leave the box empty.

• The colour, font and font size information of the first character in the text will be used.

• While we strive to match the original design as much as possible during rendering, the result is not exact. Ensure there is some padding around all sides of the text box to allow for this.

• Text boxes in shapes other than rectangles are currently not supported.

• During the design process, consider that some languages are written right to left.

Export procedure

Firstly, check that every element in the TEXT layer has been given a unique, lowercase identifier as outlined above.

Next, resize the artboard to fit to artwork bounds:

1. Ensure all layers (including the TEXT layer) are visible.

2. Click Object -> Artboards -> Fit To Artwork Bounds.

Now export the base PNG image:

1. Ensure the TEXT layer is hidden.

2. Export PNG, ensuring that Use Artboards is selected.

Finally, export the SVG file containing the text field information:

1. Ensure all layers (including the TEXT layer) are visible.

2. Click File -> Save As.

3. Use the same file name (without extension) as was used for the PNG.

4. Choose SVG as the format, and select Use Artboards.

5. Click Save.

6. In the dropdown for CSS Properties, choose Style Attributes.

7. Click OK.

For Developers

Rendering text into defined text fields (i.e. defined in an SVG file)

To dynamically render text onto the resource, use the TextBoxDrawer class.

from utils.TextBoxDrawer import TextBoxDrawer

Load the base PNG image, set it up for editing, and then instantiate a TextBoxDrawer object.

image = Image.open("my_resource.png")
draw = ImageDraw.Draw(image)
textbox_drawer = TextBoxDrawer(image, draw, svg_path="my_resource.svg")

Dynamically populate text fields by calling the write_text_box function.

textbox_drawer.write_text_box(
    "title",
    "This is some text",
    horiz_just="center",
)

Notes:

• Justification information (horizontal and vertical) is not extracted from the original design. The default is top left, but can be overrided using the kwargs horiz_just and vert_just.

• Colour, font, and font size information is extracted from the original design, but can also be set with kwargs here. If provided, kwargs will take precedence.

• See the docstrings in TextBoxDrawer.py for more detailed information on the options available.

Rendering text without defined text fields (i.e. without an SVG file)

It is also possible to use this class for dynamically rendering text without an SVG file to define the parameters of the text fields.

1. Initialise TextBoxDrawer without an SVG path.

2. Create an instance of the TextBox class to define the parameters of the text field (this is normally created automatically with the information extracted from the SVG).

3. Call write_text_box with the instantiated TextBox object instead of a textbox identifier.

A simple example:

from utils.TextBoxDrawer import TextBoxDrawer, TextBox

image = Image.open("my_resource.png")
draw = ImageDraw.Draw(image)
textbox_drawer = TextBoxDrawer(image, draw)

font_path = "static/fonts/PatrickHand-Regular.ttf"
font_size = 40

x, y = 100, 200
width, height = 300, 400

# Vertices clockwise from top left
vertices = [(x, y), (x + width, y), (x + width, y + height), (x, y + height)]

box = TextBox(vertices,
  width,
  height,
  color="#ba325b",
  font_path=font_path,
  font_size=font_size
)

textbox_drawer.write_text_box(
  box,
  "This is some text"
)

Specific Resource Details

Pixel Painter

Adding new images

Each pixel grid page contains 20 rows and 15 columns of pixels. Therefore when adding new images, the width and height should be multiples of these numbers for optimal page usage (for example 40 pixels high by 60 pixels wide).

Each image is required to be available in the following variants:

1. Black and white: The image must only contain a grayscale channel, with pixels either being white (255) or black (0).

2. Greyscale: The image must only contain a grayscale channel, and the pixels must be one of the following values:

   • 0

   • 84

   • 168

   • 255

3. Colour: The image must only contain a red, green, and blue channels (no alpha channel). Pixels must be one of the following RGB values:

   • 255, 255, 255 - White

   • 0, 0, 0 - Black

   • 255, 0, 0 - Red

   • 255, 143, 0 - Orange

   • 255, 243, 0 - Yellow

   • 76, 219, 5 - Green

   • 0, 162, 255 - Blue

   • 138, 0, 255 - Purple

Search Feature

The search feature uses Django Haystack to search indexed models. Two filters are available:

1. Filter by model.

2. Filter by related curriculum areas. The two models that have related curriculum areas:

   • Curriculum integrations.

   • Lessons (through learning outcomes with curriculum areas).

The search index indexes text using character fields, which requires exact word matches to find objects, however the character field gives fast performance.

The search page form uses multiple-select widgets to allow the user to easily select items to filter by.

Indexing of general and Classic CS Unplugged pages

Allowing the user to search for general pages (for example, the webpage on computational thinking) and Classic CS Unplugged page (for example, the graph colouring activity) was an important feature to implement. There were three main strategies to accomplish this task:

1. Modify Django Haystack to handle non-model data - This would have been a very hard approach to take (Django Haystack authors do not recommend it) as the package is built around models to its core.

2. After Django Haystack performs search, using Python to search pages - This would be very easy to implement however would lower search performance as it would occur for each request.

3. Create models for Django Haystack to index - This would involve adding models to the general and classic applications for content to be indexed.

The best strategy of these was number 3, as it didn’t require extensive rewriting of the Django Haystack package and complex searching on every request. Therefore models were added to both applications for the two types of content. Initially we converted all data into configuration files for model creation (for example, instead of manually listing all Classic CS Unplugged URLs for redirection in the url routing file, store the redirect data within the model). However Django is not setup to handle multiple URL routes all based off the pattern. For example, Django would not check a URL matches a unit plan slug after failing to find a topic:

• r"^/topics/(?P<topic_slug>[-\w]+)/$"

• r"^/topics/(?P<lesson_slug>[-\w]+)/$"

Therefore the current setup of URLs and views for the general and classic applications is left untouched, and new configuration files are added for data to be added as models. The configuration files do duplicate some data, but only for pages that are searchable.

More information on the decisions to implement this feature is available on GitHub.

Deployment

Note

This page is intended only for staff within the University of Canterbury Computer Science Education Research Group, as deployment requires access to secret passwords and values stored within our private password management system.

Requirements

The project is designed to run on the following systems:

• Google App Engine: Flexible Enviroment.

• Google Cloud SQL: Postgres Database.

  • Several Django models require Postgres specific data types, so the system will not function on a different database type (for example: MySQL).

• Static files server.

Deployment overview

Deployment requires three steps, and can be done in any order:

1. Updating static files on Google Cloud Storage Bucket.

2. Updating Django application on Google App Engine.

3. Connecting to the Google Cloud SQL database and updating schema and data.

We update in the order above to have minimal downtime between deploying a new application and updating the database (currently around 30 to 60 seconds on development deployment).

Development deployment

Deployment of the develop branch occurs automatically with new commits to the develop branch, and is deployed by Travis CI.

The system is deployed to: https://cs-unplugged-dev.appspot.com/.

The script and files used for deployment is stored in the infrastructure/develop-deploy/ directory. The develop-deploy.sh script contains descriptions of the process required for deployment. The file develop-deploy-secrets.tar.enc is an encrypted archive of files containing sensitive data, and is decypted by Travis CI.

Production deployment

Deployment of the master branch occurs automatically with new commits to the master branch, and is deployed by Travis CI.

The system is deployed to: https://www.csunplugged.org/.

Manual deployment

Warning

The following steps will allow manual deployment. This information is not exhaustive, but will provide enough information for manual deployment. The deployment scripts have greater details of the deployment process.

For any manual deployment, you will require the gcloud tool to be installed on your machine, and login with the research group admin Google account.

Manual deployment requires three steps, and can be done in any order:

1. Updating static files on Google Cloud Storage Bucket.

2. Updating Django application on Google App Engine.

3. Connecting to the Google Cloud SQL database and updating schema and data.

Updating static files

The simpliest way to upload the static files on the storage bucket, is to do the following:

1. Delete the following folders if they exist:

   • csunplugged/build/

   • csunplugged/staticfiles/

   • csunplugged/temp/

   This may require administrator (sudo) permissions as these folders are created by Docker.

2. Run the ./csu start command. When the system is started, the static files are generated. Once the system has started successfully, run the ./csu end command.

3. From the root directory, run the following command:

   $ gsutil rsync -R csunplugged/staticfiles/ gs://cs-unplugged-develop/static/
   

Updating Django application

In the infrastructure directory, create a copy of app-sample.yaml called app.yaml in the root directory, and enter the required values. The complete contents for this file is also stored in our password management system.

From the root directory, run the following command:

$ gcloud app deploy app.yaml

Updating database

To update the development database, we will setup a SQL proxy to the server, and then locally run the Django project that will connect to the server. We can then perform the migrate and updatedata commands as required.

Using the guide for Django on Google App Engine Flexible Environment, download and setup the SQL proxy. You will need to choose a port that the SQL proxy and Django will operate on, using 5432 should work for most developers. Alter the Django configuration to connect using the proxy port, and run the system. You should be able to then perform the migrate and updatedata commands.

Test Suite

Running the Test Suite

./dev test_suite will run the entire test suite. For running a specific tests, viewing code coverage, and more testing commands, see Helper Commands for Developing.

Structure

All tests are in the tests/ directory, which in the csunplugged/ directory (at the same level as the apps). It is structured as follows:

└── tests/
    ├── general/
    │   ├── management/
    │   ├── templatetags/
    │   ├── urls/
    │   └── views/
    ├── resources/
    │   ├── loaders/
    │   ├── models/
    │   ├── resource/
    │   ├── urls/
    │   ├── views/
    │   └── ResourcesTestDataGenerator.py
    ├── topics/
    │   ├── loaders/
    │   │   └── assets/
    │   ├── models/
    │   ├── urls/
    │   ├── views/
    │   └── TopicsTestDataGenerator.py
    ├── utils
    │   └── errors/
    └── BaseTestWithDB.py

Note that each app being tested has it’s own folder, and this is then broken down further into the component being tested (i.e. views, urls, models, etc).

Items of interest from this diagram:

• models/ - contains a test file for each model in the app.

• urls/ - contains a test file for each url in the app.

• views/ - contains a test file for each view in the app.

• loaders/ - contains a test file for each loader in the app as well as an assets/ directory. Test yaml files should be saved in the corresponding loader directory within assets/ and should mimick the folder structure of the app where necessary.

• Test Data Generators - these are classes used to generate place holder data in the database. You should use the methods in these files when testing a model that contains a foreign key and/or many-to-many field that needs to be populated.

• BaseTestWithDB.py - this class inherits the Django TestCase class, and creates and logs in a user. This is the base test class that all other tests should inherit from in order to interact with the database.

• utils/errors/ - contains test error classes for testing exceptions are raised correctly by the loaders.

Adding Tests

When writing a new test function, it is important that the method name is as descriptive as possible. The method name should also be prefixed with test_ as the test suite will only execute methods with this prefix.

Note

We use Codecov to check the coverage of our tests. Every Pull Request should cover 100% of the difference (therefore increasing coverage), Travis will fail if this is not the case.

Translation

Translation Principles

The following principles were used to guide the design of a translation system for CS Unplugged:

1. Translations should be ‘first class citizens’ - they should exist as independent entities from the source content, and be coupled as loosely as possible to it.

2. Translated content should remain accessible even if the source material changes, and an updated translation is not yet available.

3. Users should be able to see all content that exists, even if it is not available in their language.

4. Translated content should be presented solely in the users language, without being interspersed with English.

Translatable Files

Translatable content is stored in four types of files:

• Markdown files, for content to be processed by Verto.

• YAML files containg field translations for a given model type.

• HTML templates.

• Python code.

The first two types of file are stored inside the directory tree for a given language (ie. the directory named using the Django locale code).

Note

YAML translation files must contain translations for only one model type, but may contain translations for multiple instances of that model, and for multiple fields.

They are structured as follows

<object-slug-1>:
    <field-1>: <translated value for field-1>
    <field-2>: <translated value for field-2>
<object-slug-2>

For example, the following snippet is from the YAML translation file for all classroom resources

pens:
  description:  Pens
paper:
  description:  Paper
number-line-0-20:
  description:  Number line from 0 to 20

It is important to note that these YAML files are separate from configuration files, which are located in the structure directory.

These files can be parsed and loaded using a utility function on the TranslatableModelLoader base class.

For the latter two type of files, Django’s built-in translation support is utilised to handle translatable strings. In Python code, text is wrapped in a ugettext function call (usually aliased to _). In HTML templates, text is wrapped in {% trans %}/{% blocktrans trimmed %} tags.

Translatable Model

The TranslatableModel class is a base model class that allows content to be stored using the above principles. It is availabe in the file utils/TranslatableModel.py and should be subclassed by all models which contain any user facing content.

Django Package - modeltranslation

The Django modeltranslation package is utilised to stored translated content on a model. The basic idea is that for each translatable field, an extra database column is added for every language defined in the Django settings file. When the base field is accessed, modeltranslation performs some magic to retrieve the translation for the users language

To register translation fields for a given TranslatableModel, add a TranslationOptions subclass to the translations.py file in the relevant application. For more details, see the models already registered, or read the modeltranslation docs.

Note

The default behaviour for modeltranslation is to fallback to the English value if no translation is present. In CS Unplugged, this is desirable for text fields such as name and title, but is often undesirable for most other fields (see Translation Principles).

To disable fallback for a given field:

• Add <field name>: None to the fallback_undefined dictionary in the models TranslationOptions subclass.

• Add default="" option to the field in it’s models.py definition.

Available Languages

The TranslatableModel base class includes a mechanism to determine whether a model sufficiently translated and available in a given language.

This mechanism consists of

• The languages field, which is an array field storing the Django language codes for languages in which the model is available

• The translation_available property, which returns true if the model is available in the current language

When creating the TranslatableModel instance, the list of available languages should be determined. This will likely be decided using a list of required fields, where the presence of translations for all required fields leads to the model being marked as available. The TranslatableModelLoader base class includes functions to assist with this task

In view and template code, the translation_available property can be checked to determine the presentation of translated content (or lack thereof) on the front end.

Translatable Model Loader

The TranslatabaleModelLoader base class should be subclassed by all loaders that deal with translatable models. It provides a number of helper functions for dealing with translated content. It is availabe in the file utils/TranslatableModelLoader.py.

Utility Functions

The following utility functions are available:

• get_yaml_translations - Load translations for model fields from a given YAML file

• get_markdown_translations - Load translations for a given Markdown file

• populate_translations - Populate translation fields on a model using values in a given dictionary

• mark_translation_availability - Modify languages field to contain all languages for which all required translation fields are populated

Refer to the function docstrings for more detailed documentation. It may also be useful to refer to existing loader implementations to understand how these functions can be used.

Translation Infrastructure

Note

The in-context translation has been removed temporarily as translation infrastructure is being updated. We aim to re-add this feature in a future update.

Crowdin

We use a localisation management platform called Crowdin for translation of CS Unplugged. The project is public, meaning that anyone can create an account and contribute translations.

Translatable Files

There are 3 types of files that contain translatable content:

• Content Markdown files

• Content YAML files containg translatable model strings

• django.po file containing translatable system strings

Translatable source files must always reside under an en directory tree. Translated files are downloaded into a directory named with the language’s locale code, and with the same structure as the source tree.

Note

The locale code differs from the language code in format - where a language code is of form ab-cd, the locale code will be ab_CD. Directories must be named using the locale code recognised by django for that language.

For more information, see

• https://docs.djangoproject.com/en/1.11/topics/i18n/

• https://github.com/django/django/tree/master/django/conf/locale

• https://github.com/django/django/blob/master/django/utils/translation/trans_real.py#L59

The configuration specifying which files should be uploaded for translation is stored in the file crowdin.yaml in the repository root. Details about the structure of this file are available in the Crowdin documentation.

Review Process

For a translation of any given string to make it to production release, it must pass the following stages of review:

1. (Crowdin) Translation Proofread - Review by a second translator with ‘proofreader’ status in the target language.

2. (GitHub) Technical Review - Review by a member of the CS Unplugged technical team to catch technical errors (i.e. with Verto tags, links, Markdown syntax etc). Automated testing on travis will also occur at this stage.

Translation Pipeline

The translation pipeline is implemented by the Crowdin GitHub Action. The following diagram gives a broad overview of the translation pipeline. The blue arrows indicate the path from a source file change through to the release of the translation for that change.

Other Documentation

Frequently Asked Questions

The topics application is the main focus of the CS Unplugged website, as it contains the majority of educational material for the project.

What is a Key?

We use the term “key” to specify a field name. Keys map to particular values (which range from learning outcome text, to the structure and attributes of a lesson).

A key is a short label for something, containing only letters, numbers, or hyphens. In our system, a key must be no longer than 50 characters, and use hyphens instead of underscores.

These are valid examples of keys:

• algorithms

• binary-numbers

• challenge-2

These are invalid examples of keys:

• Algorithms

• Binary Numbers

• Binary_Numbers

• binary_numbers

• challenge 2

Keys must be exact matches to work, for example, if you name a lesson bits-and-bytes, referencing it in another configuration file as bytes-and-bits will raise an error.

See also:

• Definition of URL slug on Wikipedia

What is an Application?

Django contains ‘applications’ which are Python packages that provide some set of features. Each large part/chunk of the CS Unplugged is a separate application. Read this section in our project structure guide for details of the applications used in the CS Unplugged system.

What is a Virtual Environment?

A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the “Project X depends on version 1.x but, Project Y needs 4.x” dilemma, and keeps your global site-packages directory clean and manageable.

See also:

• Guide on Virtual Environments

Setting up a Virtual Machine

The following steps are just one way to set up an Linux virtual machine for CS Unplugged development, and are intended for those new to setting up virtual machines.

1. Download and install Oracle VirtualBox.

2. Download installation of preferred Linux operating system. A common choice is Ubuntu 16.04.2 LTS.

3. Open VirtualBox and click New.

4. Enter a name for your virtual machine, for example “CS Unplugged”. Also select the type and version of your operating system. If you downloaded the Ubuntu linked above, the type is “Linux”, and version is “Ubuntu (64-bit)”. Click “Next/Continue”.

5. Choose the memory you wish to allocate (2048 MB to 4096 MB is recommended). Click “Next/Continue”.

6. Select “Create a virtual hard disk now”. Click “Create”.

7. Keep the default selection of “VDI (VirtualBox Disk Image)”. Click “Next/Continue”.

8. Keep the default selection of “Dynamically allocated”. Click “Next/Continue”.

9. Change the name and location of the hard drive for the virtual machine if required (default is usually fine).

10. Select the maximum size that the hard drive can grow to (be aware of how much space you have available on your machine). We recommend 20 GB, as this is enough space to store the Ubuntu operating system and the CS Unplugged project. Click “Create”.

11. Select your virtual machine by clicking on it, and click “Settings” above. Within these settings you can also setup a shared clipboard between the host and virtual machines, plus increase the number of processors the virtual machine can use. There are plenty of guides available online for how to enable them.

12. Click the “Storage” category. Under “Controller: IDE” click “Empty”. On the right of Optical Drive dropdown menu, click the CD disk icon. Select “Choose Virtual Optical Disk File” and select the operating system installation file that you downloaded earlier (it’s probably in your “Downloads” folder). Close the Settings window.

13. Select the virtual machine by clicking on it and click the green “Start” button above. The operating system installation screen should appear upon starting.

14. Install the operating system using the default settings.

15. Once the operating system has completed installation, you are ready to use it for developing the CS Unplugged project. You’re now ready for Step 2: Install Git in the installation guide.

Troubleshooting

dev helper script

I get a No such file or directory error when running the dev script

Check your terminal working directory is within the cs-unplugged directory, the root directory of the project. Running the ls command in this directory should list the dev file.

I have an error when running ./dev start

If you are having issues running the start command, try rebuilding the system images with ./dev build. Changes may be have been made to the system images since you initally created them.

If this still doesn’t solve your problem, you could also try deleting any existing images with ./dev wipe, and then build and start the system with ./dev start.

If issue still persists, log a bug on our issue tracker.

Viewing website

Images are not displayed when I view the website

Firstly check the image is located in the staticfiles/ directory. If the image isn’t located within the directory, check the original image is located within the static directory.

Normal Images (not Scratch block images)

If the image is located within the static/ directory, check the filepath is correct. When running ./dev update, the script will report an error if an image cannot be found.

Scratch block images

Check the .txt files located within the temp/ directory for a file containing the Scratch block syntax for the image missing (project wide find & replace is your friend here).

If you can find the file with the same block syntax and there isn’t a image in the staticfiles/ directory with the same filename (.svg instead of .txt), try running ./dev update. If this doesn’t fix the problem, the problem is in our scripts so log a bug on our issue tracker.

If you can’t find a file within the temp/ directory, check the syntax used in the text is valid. If the syntax is valid, the problem is in our Markdown to HTML converter to log a bug on our issue tracker.

Changed CSS/SCSS styles are not updated when I view the website

Firstly check the compiled CSS is located in the staticfiles/ directory, and that the changes have appeared in the compiled CSS file. If the CSS file does not include the changes made, run ./dev static. If you are editing SCSS files, check the ./dev static command isn’t reporting SCSS compilation errors.

The website isn’t displaying when I open cs-unplugged.localhost in a browser

Check you have run the ./dev start command, and that it hasn’t reported any errors.

Changelog

This page lists updates to CS Unplugged. All notable changes to this project will be documented in this file.

Note

We base our numbering system from the guidelines at Semantic Versioning 2.0.0, for versions 4.0.0-alpha.1 onwards.

Given a version number MAJOR.MINOR.HOTFIX:

• MAJOR version change when major backend or text modifications are made (for example: new topic).

• MINOR version change when content or functionality is added or updated (for example: new videos, new activities, large number of text (typo/grammar) fixes).

• HOTFIX version change when bug hotfixes are made (for example: fixing a typo).

• A pre-release version is denoted by appending a hyphen and the alpha label followed by the pre-release version.

As this project contains text content, the updating of content doesn’t perfectly fit the Semantic Versioning model. However these version numbers can still provide a good indication of the changes in each version.

7.3.0

Release date: 15 December 2022

Changelog:

• Update infrastructure to fix issues with local development on multi-user Linux machines.

• Update panel documentation to include information about supported panel types.

• Update panel example in documentation to use the new format.

• Set English as the default langauge for the local docs server.

• Update project structure to be more inline with the current state of the project.

• Fix majority of loading bugs caused by 7.2.0.

• Bring documentation for helper commands up to date.

• Dependency updates:

  • Update jquery from 3.6.1 to 3.6.2.

  • Update lxml from 4.9.1 to 4.9.2.

  • Update crowdin/github-action from 1.4.16 to 1.5.2.

  • Update postcss from 8.4.18 to 8.4.20.

  • Update pypdf2 from 2.11.1 to 2.12.1.

  • Update sass from 1.56.0 to 1.56.2.

  • Update django-modeltranslation from 0.18.5 to 0.18.7.

  • Update dependabot/fetch-metadata from 1.3.4 to 1.3.5.

  • Update yargs from 17.6.0 to 17.6.2.

  • Update sphinx-rtd-theme from 1.1.0 to 1.1.1.

  • Update django-debug-toolbar from 3.7.0 to 3.8.1.

  • Update actions/setup-python from 4.3.0 to 4.3.1.

7.2.1

Release date: 3 November 2022

Changelog:

• Update embedded ‘At home’ videos to UCCSER original versions. Previous versions were modified variants.

• Fix typo of wrong version number in changelog.

7.2.0

Release date: 2 November 2022

Changelog:

• Add new lesson ‘Squeezing pictures into less space’ for ages 5 to 10 within the ‘Image Representation’ topic.

• Add ‘Run Length Encoding Worksheet’ printable.

• Add new ‘At a distance’ lessons:

  • Parity Magic

  • QR Codes

  • Product Code Check Digits

  • Image Compression

  • Information Theory

• Updated existing ‘At a distance’ lessons, to be consistent with new content:

  • The Stroop Effect

  • Algorithms

  • Binary Representation

  • Finite State Automata

• Open links within ‘At a distance’ content in a new tab.

• Clarify prompt for closing ‘At a distance’ slides starting modal.

• Update existing content instead of deleting and recreating content. Used to remove downtime of content upon deployments.

• Fix bug where a nested details element would use icon state from parent details element.

• Switch to Plausible analytics.

• Dependency updates:

  • Update actions/setup-python from v2 to v4.3.0.

  • Update autoprefixer from 10.4.11 to 10.4.13.

  • Update coverage from 6.4.4 to 6.5.0.

  • Update crowdin/github-action from 1.4.13 to 1.4.16.

  • Update cssnano from 5.1.13 to 5.1.14.

  • Update cssselect from 1.1.0 to 1.2.0.

  • Update dependabot/fetch-metadata from v1.3.3 to v1.3.4.

  • Update django from 3.2.15 to 3.2.16.

  • Update django-debug-toolbar from 3.6.0 to 3.7.0.

  • Update django-modeltranslation from 0.18.4 to 0.18.5.

  • Update docker/build-push-action from v2.8.0 to v3.2.0.

  • Update docker/login-action from v2.0.0 to v2.1.0.

  • Update Pillow from 9.2.0 to 9.3.0.

  • Update postcss from 8.4.16 to 8.4.18.

  • Update psycopg2 from 2.9.3 to 2.9.5.

  • Update PyPDF2 from 2.10.8 to 2.11.1.

  • Update reveal.js from 4.3.1 to 4.4.0.

  • Update sass from 1.54.9 to 1.55.0.

  • Update scratchblocks from UCCSER version to official 3.6.1. Our changes were accepted within the official repository.

  • Update sphinx-rtd-theme from 1.0.0 to 1.1.0.

  • Update uniseg from 0.7.1.post2 to 0.7.2.

  • Update yargs from 17.5.1 to 17.6.0.

7.1.0

Release date: 18 September 2022

Changelog:

• Add ‘Finite State Automata’ to ‘At a distance’ lessons

• Capitalise reference to Classic CS Unplugged resource.

• Add redirect for old URL.

• Update project to use uccser-development-stack v3.

• Remove character within Crowdin config that caused workflow to fail.

• Dependency updates:

  • Update autoprefixer from 10.4.8 to 10.4.11.

  • Update crowdin/github-action from 1.4.12 to 1.4.13.

  • Update django-extensions from 3.2.0 to 3.2.1.

  • Update jquery from 3.6.0 to 3.6.1.

  • Update PyPDF2 from 2.10.2 to 2.10.8.

  • Update sass from 1.54.4 to 1.54.9.

  • Update tqdm from 4.64.0 to 4.64.1.

7.0.0

Release date: 11 August 2022

Summary of changes:

This release adds the ‘At a distance’ area of the website.

Changelog:

• Add ‘At a distance’ area of the website for teaching CS Unplugged remotely:

  • Includes three lessons:

    • Stroop Effect

    • Algorithms

    • Binary Representation

  • Six more planned to be released before the end of 2022.

  • Each lesson includes presentation slides with speaker notes.

• Remove unit plans from topics, the content of these unit plans have been moved to the topic.

  • Unit plans were initially as we planned for storing multiple unit

• Update ‘Binary Windows’ printable to be only one page, and have 5 and 6 bit options.

• Replace blurry images of ‘At home’ challenges within ‘Unlocking the secret in product codes’.

• Update Chinese (Simplified) and French translations.

• Add tiled background for ‘Plugging it in’ homepage.

• Remove elasticsearch as search dependency and use Full Text Search (FTS) within Postgres.

• Show full Git SHA on development website.

• Suppress gunicorn access and error logs during local development.

• Remove unused ‘dev’ application (local development sitemap).

• Remove outdated xx_LR/yy_RL language files used for unsupported in-context translation feature provided by Crowdin.

• Update Gulp SCSS task to only update files changed since last run.

• Update test coverage to codecov.

• Update documentation to use ‘dev’ script, instead of deprecated ‘csu’ script.

• Auto-merge minor dependency updates (this includes minor and patch updates).

• Allow all dependency update pull requests to be created (remove open limit on Dependabot).

• Ignore updates to non-LTS Django packages.

• Add OCI labels to Django Docker image.

• Update license year.

• Use modified Sniglet font with macron support for Te Reo Māori.

• Dependency updates:

  • Add decktape 3.4.1.

  • Add gulp-dependents 1.2.5.

  • Add reveal.js 4.3.1.

  • Update actions/checkout from v2 to v3.

  • Update actions/upload-artifact from v2 to v3.

  • Update ansi-colors from 4.1.1 to 4.1.3.

  • Update autoprefixer from 10.4.2 to 10.4.8.

  • Update bootstrap from 4.6.0 to 4.6.1.

  • Update browser-sync from 2.27.7 to 2.27.10.

  • Update codemirror from 5.65.1 to 5.65.6.

  • Update coverage 6.2 to 6.4.4.

  • Update crowdin/github-action from 1.4.6 to 1.4.12.

  • Update cssnano from 5.0.15 to 5.1.13.

  • Update django from 3.2.11 to 3.2.15.

  • Update django-cors-headers from 3.11.0 to 3.13.0.

  • Update django-debug-toolbar from 3.2.4 to 3.6.0.

  • Update django-environ from 0.8.1 to 0.9.0.

  • Update django-extensions from 3.1.5 to 3.2.0.

  • Update django-modeltranslation from 0.17.3 to 0.18.4.

  • Update docker/metadata-action from v3 to v4.

  • Update download-artifact from v2 to v3.

  • Update login-action from v1.12.0 to v2.0.0.

  • Update lxml from 4.7.1 to 4.9.1.

  • Update Pillow from 9.0.0 to 9.2.0.

  • Update postcss from 8.4.5 to 8.4.16.

  • Update postgres from 13.3 to 13.6.

  • Update PyPDF2 from 1.26.0 to 2.10.2.

  • Update requests from 2.27.1 to 2.28.1

  • Update sass from 1.49.0 to 1.54.4.

  • Update tqdm from 4.62.3 to 4.64.0.

  • Update whitenoise from 5.3.0 to 6.2.0.

  • Update yargs from 17.3.1 to 17.5.1.

  • Remove django-haystack[elasticsearch] 3.1.1.

  • Remove django-widget-tweaks 1.4.12.

  • Remove elasticsearch 5.5.3.

6.5.0

Release date: 19th December 2021

Changelog:

• Add block based programming language for Plugging It In.

• Update information on Online Courses page.

• Update logging configuration.

• Update team members.

• Enable CORS headers for providing version information.

• Dependency updates: - Add blockly 7.20211209.2. - Add django-cors-headers 3.11.0. - Update autoprefixer from 10.3.7 to 10.4.2. - Update browser-sync from 2.27.5 to 2.27.7 - Update codemirror from 5.63.3 tp 5.65.1. - Update coverage from 6.0.2 to 6.2. - Update crowdin/github-action from 1.4.0 to 1.4.6. - Update cssnano from 5.0.8 to 5.0.15. - Update django from 3.2.8 to 3.2.11. - Update django-debug-toolbar from 3.2.2 to 3.2.4. - Update django-environ from 0.7.0 to 0.8.1. - Update django-extensions from 3.1.3 to 3.1.5. - Update django-widget-tweaks from 1.4.8 to 1.4.12. - Update docker/login-action from 1.10.0 to 1.12.0. - Update fancy-log from 1.3.3 tp 2.0.0. - Update gulp-sass from 5.0.0 to 5.1.0. - Update intro.js from 4.2.2 to 4.3.0. - Update lxml from 4.6.3 to 4.7.1. - Update Pillow from 8.3.2 to 9.0.0. - Update postcss from 8.3.9 to 8.4.5. - Update psycopg2 from 2.9.1 to 2.9.3. - Update sass from 1.43.2 tp 1.49.0. - Update yargs from 17.2.1 to 17.3.1.

6.4.0

Release date: 17th November 2021

Changelog:

• Add ‘Online Courses (MOOCs)’ area of the website: - Added first course with links to supporting resources. - Update notice on homepage to link to new course.

• Add new Classic CS Unplugged logo.

• Fix grammar in several lessons.

• Expand ‘BST’ acronym in learning outcomes.

• Add Django system check to required checks in testing and deployment pipeline.

• Set Traefik redirect middleware to have a unique name.

• Dependency updates: - Update autoprefixer from 10.3.6 to 10.3.7. - Update codemirror from 5.63.1 to 5.63.3. - Update postcss 8.3.8 to 8.3.9. - Update sass 1.42.1 to 1.43.1. - Update django from 3.2.7 to 3.2.8. - Update PyYAML from 5.4 to 6.0. - Update flake8 from 3.9.2 to 4.0.1. - Update coverage from 5.5 to 6.0.2.

6.3.0

Release date: 4th October 2021

Changelog:

• New topic “Data structures for searching”:

  • Includes binary search trees lesson, aimed at ages 11 to 14. #1559

• Add Māori subtitles for videos.

• Move website from Google Cloud Platform to Docker Swarm hosted at the University of Canterbury. #1616

  • Modifies website infrastructure to use Docker Swarm, running all website components as services.

  • Static files are now served by Django.

  • Use GitHub actions for automated workflows. This includes testing, deployment, and internationalisation jobs.

  • Simplify static file pipeline, runs as separate Docker service.

• Scratch blocks are updated from Scratch 2 to Scratch 3.

• Fix bug when plural was displayed when there is only one object.

• Update links to Classic CS Unplugged.

• Add open/close icon to detail panels.

• Simplify flags for makeresources management command.

• Switch to GitHub dependency manager.

• Dependency changes:

  • Add ansi-colors 4.1.1.

  • Add browser-sync 2.27.5.

  • Add cssnano 5.0.8.

  • Add del 4.1.1.

  • Add django-haystack[elasticsearch] 3.1.1.

  • Add elasticsearch 5.5.3.

  • Add fancy-log 1.3.3.

  • Add gulp-concat 2.6.1.

  • Add gulp-error-handle 1.0.1.

  • Add gulp-imagemin 7.0.0.

  • Add pixrem 5.0.0.

  • Add postcss 8.3.8.

  • Add sass 1.42.1.

  • Add whitenoise 5.3.0.

  • Update autoprefixer from 9.5.1 to 10.3.6.

  • Update bootstrap from 4.4.1 to 4.6.0.

  • Update browserify from 16.2.3 to 17.0.0.

  • Update codemirror from 5.52.2 to 5.63.1.

  • Update coverage from 5.3.1 to 5.5.

  • Update crowdin/github-action from 1.0.18 to 1.4.0.

  • Update django from 2.2.12 to 3.2.6.

  • Update django-debug-toolbar from 3.1.1 to 3.2.2.

  • Update django-environ from 0.4.5 to 0.7.0.

  • Update django-extensions from 3.0.9 to 3.1.3.

  • Update django-modeltranslation from 0.16.1 to 0.17.3.

  • Update flake8 from 3.8.4 to 3.9.2.

  • Update gulp-filter from 5.1.0 to 7.0.0.

  • Update gulp-if from 2.0.2 to 3.0.0.

  • Update gulp-postcss from 8.0.0 to 9.0.1.

  • Update gulp-sass from 4.0.2 to 5.0.0.

  • Update gulp-sourcemaps from 2.6.5 to 3.0.0.

  • Update gulp-tap from 1.0.1 to 2.0.0.

  • Update gulp-terser from 1.1.7 to 2.1.0.

  • Update gunicorn from 19.9.0 to 20.1.0.

  • Update intro.js from 2.9.3 to 4.2.2.

  • Update jquery from 3.4.1 to 3.6.0.

  • Update multiple-select 1.2.1 to 1.5.2.

  • Update Pillow from 8.1.0 to 8.3.2.

  • Update popper.js from 1.15.0 to 1.16.1.

  • Update postcss-flexbugs-fixes from 4.1.0 to 5.0.2.

  • Update psycopg2 from 2.7.6.1 to 2.9.1.

  • Update pydocstyle from 5.1.1 to 6.1.1.

  • Update PyYAML from 5.3.1 to 5.4.

  • Update requests from 2.25.1 to 2.26.0.

  • Update scratchblocks from 3.1.2 to UCCSER variant.

  • Update sphinx from 3.4.3 to 4.2.0.

  • Update sphinx-rtd-theme from 0.5.1 to 1.0.0.

  • Update tqdm from 4.51.0 to 4.62.3.

  • Update uniseg from 0.7.1 to 0.7.1.post2.

  • Update verto from 0.10.0 to 1.0.1.

  • Update weasyprint from 52.2 to 52.4.

  • Update yargs from 13.2.4 to 17.2.1.

  • Update yattag from 1.12.2 to 1.14.0.

  • Remove django-haystack.

  • Remove gulp-jshint.

  • Remove gulp-notify.

  • Remove gulp-rename.

  • Remove gulp-util.

  • Remove gulplog.

  • Remove jshint-stylish.

  • Remove jshint.

  • Remove request.

  • Remove run-sequence.

  • Remove sticky-state.

  • Remove through2.

  • Remove wheel.

  • Remove Whoosh.

6.2.1

• Release date: 17th February 2021

• Downloads: Source downloads are available on GitHub

Changelog:

• Fix bug where not all printable PDFs were generated.

• Update test suite to cover basic infrastructure tasks.

6.2.0

• Release date: 16th February 2021

• Downloads: Source downloads are available on GitHub

Changelog:

• Add initial French language content:

  • Four lessons for Binary Numbers topic.

  • All printables.

  • All glossary definitions.

• Update contributors list.

• Switch to Crowdin GitHub Action for updating translation files.

• Switch to using Dependabot for tracking dependency updates.

• Dependency updates:

  • Update coverage from 5.2.1 to 5.3.1.

  • Update django-debug-toolbar from 2.2 to 3.1.1.

  • Update django-extensions from 3.0.8 to 3.0.9.

  • Update django-haystack from 2.8.1 to 3.0.

  • Update django-modeltranslation from 0.15.2 to 0.16.1.

  • Update flake8 from 3.8.3 to 3.8.4.

  • Update Pillow from 7.2.0 to 8.1.0.

  • Update requests from 2.24.0 to 2.25.1.

  • Update sphinx from 3.2.1 to 3.4.3.

  • Update sphinx-rtd-theme from 0.5.0 to 0.5.1.

  • Update tqdm from 4.48.2 to 4.51.0.

6.1.3

• Release date: 8th December 2020

• Downloads: Source downloads are available on GitHub

Changelog:

• Remove the following folders when deploying to production:

  • csunplugged/build

  • csunplugged/temp

  • csunplugged/staticfiles

6.1.2

• Release date: 8th December 2020

• Downloads: Source downloads are available on GitHub

Changelog:

• Ignore the csunplugged/build/img folder in Google Cloud.

6.1.1

• Release date: 8th December 2020

• Downloads: Source downloads are available on GitHub

Changelog:

• Add 3 ‘At home’ activities:

  • Guess my number

  • Find my card

  • Guess the sentence

• Dependency updates:

  • Update lxml from 4.5.2 to 4.6.2.

6.0.1

• Release date: 15th October 2020

• Downloads: Source downloads are available on GitHub

Changelog:

• Fix bug that allowed a user to insert working HTML into their copy of a Plugging it in challenge template.

6.0.0

• Release date: 8th October 2020

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release adds the ‘Plugging it in’ area of the website.

Changelog:

• Add ‘Plugging it in’ area of the website:

  • Includes 21 programming challenges in Python for Binary Numbers.

  • Includes 9 programming challenges in Python for Kidbots.

  • Saves a users code attempt and their status on the question.

  • User code tested on the JOBE server.

  • Scratch questions are not supported.

  • User triggered walk-through on programming challenge page.

• Add learning outcome and solution content to programming challenges table in the educators area.

• Replace content under the Python dropdown on programming challenge pages in CSU with a link to the same challenge in Plugging it in.

• Order glossary terms alphabetically for all languages.

• Solutions provided on the standard CSU site now pass the tests for the respective programming challenge on the CSU Plugging it in site.

• Host videos on Vimeo instead of YouTube.

• Re-number product code check digits programming challenges.

• Edit the formatting of subtitle files for Vimeo.

• Put testing examples for programming challenges into a separate markdown file.

• Add Google Tag Manager.

• Minor content fixes.

• Dependency updates:

  • Update coverage from 5.1 to 5.2.1.

  • Update django-modeltranslation from 0.14.1 to 0.15.2.

  • Update django-extensions from 2.2.9 to 3.0.8.

  • Update flake8 from 3.8.2 to 3.8.3.

  • Update lxml from 4.5.1 to 4.5.2.

  • Update Pillow from 7.1.2 to 7.2.0.

  • Update pydocstyle from 5.0.2 to 5.1.1.

  • Update requests from 2.23.0 to 2.24.0.

  • Update sphinx from 3.0.4 to 3.2.1.

  • Update sphinx-rtd-theme from 0.4.3 to 0.5.0.

  • Update tqdm from 4.46.1 to 4.48.2.

  • Update wheel from 0.34.2 to 0.35.1.

5.1.1

• Release date: 8th July 2020

• Downloads: Source downloads are available on GitHub

Changelog:

• Correction of font colour for digits in Product Code unit.

5.1.0

• Release date: 1st July 2020

• Downloads: Source downloads are available on GitHub

Changelog:

• Add video to the end of the ‘What is Computer Science?’ page.

• Show ‘plugging it in’ pages everywhere except on production.

5.0.1

• Release date: 11th June 2020

• Downloads: Source downloads are available on GitHub

Changelog:

• Fix bug in ‘unlocking the secret in product codes’ challenge number 4.

• Add introduction video to the mind reading magic challenge.

• Remove outdated demonstration video from mind reading magic more information section.

• Minor content fixes.

5.0.0

• Release date: 3rd June 2020

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release adds the ‘At Home’ area of the website, and restructures the homepage for future areas.

Changelog:

• Add ‘At Home’ area of the website:

  • Includes 5 activities.

  • Includes challenges that are tested locally, with answered stored anonymously on the database for analysis.

  • Enables admin application to allow reading of challenge submissions.

• Update homepage to organise links for educators, home use, and students.

• Update base Docker images to use Debian 10, Python 3.8.3, and Django 2.2.12.

• Set static files to be uploaded using multiprocessing.

• Dependency updates:

  • Add requests 2.23.0.

  • Update coverage from 5.0 to 5.1.

  • Update django-bootstrap-breadcrumbs from 0.9.1 to 0.9.2.

  • Update django-debug-toolbar from 2.1 to 2.2.

  • Update django-extensions from 2.2.5 to 2.2.9.

  • Update django-widget-tweaks from 1.4.5 to 1.4.8.

  • Update flake8 from 3.7.9 to 3.8.2.

  • Update lxml from 4.4.2 to 4.5.1.

  • Update Pillow from 6.2.1 to 7.1.2.

  • Update pydocstyle from 5.0.1 to 5.0.2.

  • Update PyYAML from 5.2 to 5.3.1.

  • Update sphinx from 2.3.0 to 3.0.4.

  • Update tqdm from 4.40.2 to 4.46.1.

  • Update wheel from 0.33.6 to 0.34.2.

4.4.0

• Release date: 1st April 2020

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release add a new CS Unplugged at home section.

Changelog:

• Add ‘At home’ application, with basic activities before new content is released.

• Darken colours to improve readability of white text on backgrounds.

• Update logo to increase the size of the ‘CS’ and lessened the rounded corners to improve readability.

• Separate core HTML structure in templates to allow subsites to exist.

• Update static pipeline to use NPM, based off other UCCSER repositories.

• Add ‘dev’ helper script to align with other UCCSER repositories.

4.3.0

• Release date: 20th December 2019

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release adds the image representation topic, along with new lessons for the Māori language.

Changelog:

• Add Image Representation topic, which includes one lesson for ages 5 to 10. #1225

• Add Māori content: - Two Kidbot (Ngā Karetao Tamariki) lessons. - Two Error Detection and Correction (Te rapu me te whakatikatika i ngā hapa) lessons. - Glossary definitions.

• Improve links to Computational Thinking and CS Unplugged page. #1203

• Change Pixel Painter legend to reverse digits for 1 and 0. #1220

• Add new single page variations for Pixel Painter printable.

• Add button on topics page to link to classic topic list. #985

• Fix bug when viewing programming language questions that are not translated.

• Remove deprecated custom Google App Engine health check logic.

• Update documentation for topics application. #1205

• Update flow charts in author/topics documentation page. #749

• Dependency updates:

  • Update coverage from 4.5.2 to 5.0.

  • Update cssselect from 1.0.3 to 1.1.0.

  • Update django-debug-toolbar from 1.11 to 2.1.

  • Update django-extensions from 2.1.6 to 2.2.5.

  • Update django-modeltranslation from 0.13 to 0.14.1.

  • Update django-widget-tweaks from 1.4.3 to 1.4.5.

  • Update flake8 from 3.7.7 to 3.7.9.

  • Update lxml from 4.2.5 to 4.40.2.

  • Update Pillow from 5.4.1 to 6.2.1.

  • Update pydocstyle from 3.0.0 to 5.0.1.

  • Update python-bidi from 0.4.0 to 0.4.2.

  • Update python-markdown-math from 0.5 to 0.6.

  • Update PyYAML from 5.1 to 5.2.

  • Update sphinx from 2.0.0 to 2.2.2.

  • Update sphinx from 2.2.2 to 2.3.0.

  • Update tqdm from 4.28.1 to 4.40.2.

  • Update wheel from 0.33.1 to 0.33.6.

  • Update yattag from 1.11.1 to 1.12.2.

4.2.1

• Release date: 2nd April 2019

• Downloads: Source downloads are available on GitHub

Changelog:

• Fix bug where Te Reo Māori language data was not added to Django.

4.2.0

• Release date: 1st April 2019

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release adds Te Reo Māori, Simplified Chinese (简体中文), and German (Deutsche) content, along with many bugfixes.

Changelog:

• Added Simplified Chinese (简体中文) language, currently the following pages are available: - All basic pages - All printables - Binary numbers topic: one lesson for 8 to 10 year olds, and 3 curriculum integrations.

• Added Te Reo Māori language, currently the following pages are available: - All basic pages - All printables

• Added new German (Deutsche) content: - Kidbots topic has 2 lessons for 5 to 7 year olds, and 4 curriculum integrations. - Sorting networks topic has 2 lessons for 5 to 7 year olds, and 2 curriculum integrations. - Additional content to the binary numbers topic includes 2 new lessons for 8 to 10 year olds, and 4 more curriculum integrations.

• Added 17 glossary definitions. #472

• Added ‘Treasure Island’ printable.

• Added description of alphabet on ‘Binary to Alphabet’ printable if required.

• Removed use of SVG for adding labels to ‘Job Badges’ printable.

• Added ‘Kauri Tree’ option for ‘Sorting Network Cards’ printable.

• Removed ‘Māori colours’ and ‘Māori numbers’ option from ‘Sorting Network Cards’ printable, these are now accessed through the Te Reo Māori language.

• Added ‘alt’ descriptions to images for greater content accessibility.

• Fixed various minor text corrections across content.

• Listed sponsors in README document.

• Fixed incorrect statement on ‘Pixel Painter’ printable description page.

• Removed extra spaces around programming language ages. #1151

• Simplified logic required for translation is not available badges within templates.

• Added warning to printable if translation is not available.

• Removed files of printable thumbnails, and use generated thumbnails.

• Replace translation pipeline ‘crowdin bot’ with new ‘Arnold system’.

• Added ‘lite_update’ command for only loading key content for development.

• Package updates:

  • Update wheel from 0.31.1 to 0.33.1.

  • Update Pillow from 5.2.0 to 5.4.1.

  • Update yattag from 1.10.0 to 1.11.1.

  • Update verto from 0.7.4 to 0.10.0.

  • Update django-widget-tweaks from 1.4.2 to 1.4.3.

  • Update PyYAML from 4.2b4 to 5.1.

  • Update tqdm from 4.25.0 to 4.28.1.

  • Update lxml from 4.2.4 to 4.2.5.

  • Update django-modeltranslation from 0.12.2 to 0.13.

  • Update sphinx from 1.7.7 to 2.0.0.

  • Update sphinx-rtd-theme from 0.4.1 to 0.4.3.

  • Update django-debug-toolbar from 1.9.1 to 1.11.

  • Update django-extensions from 2.1.0 to 2.1.6.

  • Update flake8 from 3.5.0 to 3.7.7.

  • Update pydocstyle from 2.1.1 to 3.0.0.

  • Update coverage from 4.5.1 to 4.5.2.

  • Removed gsutil dependency.

4.1.0

• Release date: 24th August 2018

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release focuses on adding multingual support, with limited versions of the website available in German (Deutsche) and Spanish (Español).

Changelog:

• Enable German (Deutsche) language, currently the following pages are available: - All basic pages - All printables - Binary numbers topic: one lesson for 5 to 7 year olds, and 3 curriculum integrations.

• Enable Spanish (Español) language, currently the following pages are available: - All basic pages - All printables - Binary numbers topic: one lesson for 8 to 10 year olds, and 7 curriculum integrations.

• Add Python implementations for many existing programming challenges.

• Modify ‘Treasure Hunt’ printable to ‘Number Hunt’, due to redesign of activity for universal use (English language concepts were being used).

• Modify ‘Piano Keys’ printable to allow different types of key labels.

• Modify printable PDF generation to include all languages.

• Modify printable thumbnail generation to only create English language (add warning when displaying thumbnail in non-English language).

• Use Bootstrap styling for printable generation form.

• Allow custom layout of printables in PDF generation.

• Lock website search to English only, until multilingual search is implemented. #989

• Add Travis CI status to README for each website. #1003

• Add name labels to Travis CI jobs. #996

• Add configuration file for link checker and translation syncer.

• Package updates:

  • Update django to 1.11.14.

  • Update django-bootstrap-breadcrumbs to 0.9.1.

  • Update django-extensions to 2.1.0.

  • Update django-haystack to 2.8.1.

  • Update django-widget-tweaks to 1.4.2.

  • Update gsutil to 4.33.

  • Update lxml to 4.2.4.

  • Update Pillow to 5.2.0.

  • Update python-markdown-math to 0.5.

  • Update PyYAML to 4.2b4.

  • Update sphinx to 1.7.7.

  • Update sphinx-rtd-theme to 0.4.1.

  • Update tqdm to 4.25.0.

  • Update verto to 0.7.4.

  • Update wheel to 0.31.1.

4.0.2

• Release date: 21st February 2018

• Downloads: Source downloads are available on GitHub

Changelog:

• Allow searching for general pages and Classic CS Unplugged pages. #799

• Update navigational bar. #885

• Remove admin application. #781

• Update Barcode Checksum Poster design. #877

• Fix Kidbots illustration. #875

• Fix positioning of programming challenge language implementation icon.

• Package updates:

  • Update django-haystack to 2.7.0.

  • Update sphinx to 1.7.0.

  • Update coverage to 4.5.1.

  • Add cssselect 1.0.3.

4.0.1

• Release date: 7th February 2018

• Downloads: Source downloads are available on GitHub

Changelog:

• Fix bug where logo isn’t centered in mobile navbar. #863

• Increase size of pixel painter resource thumbnails. #866

• Remove redundant headings in related lessons table for printable. #857

• Redesign topic page to add emphasis to lessons. #864

• Add 404 page when a page cannot be found. #851

• Only prepend www for production website. #860

• Update repository README file for version 4.0.0 release.

4.0.0

• Release date: 5th February 2018

• Downloads: Source downloads are available on GitHub

Summary of changes:

This is the official release of the rewritten CS Unplugged to the csunplugged.org domain, while the existing Wordpress site is archived to classic.csunplugged.org.

This release adds search functionality, while also adding new lessons for 5 to 7 year olds in the searching algorithms topic. Also included are many small improvements such as better printing of webpages, clearer video and learning outcome panels, new learning outcomes, and many more.

Changelog:

• Add search feature. #789

• Add sequential and binary search lessons for ages 5 to 7. #807

• Optimise all images #801

• Change term ‘Resources’ to ‘Printables’. #787

• Allow pre-filling of resource forms. #768

• Update relative link template to allow query parameters.

• Add welcome message to homepage. #850

• Add print view CSS. #175

• Add all example classroom videos at appropriate positions. #842

• Update binary numbers topic description. #365

• Add learning outcomes for lesson 2 (8-10) for Error Correction and Detection. #419

• Update the wording on reinforcing sequencing junior. #630

• Add GitHub Code of Conduct page that points to page in docs. #829

• Fix bug where learning outcomes were displayed multiple times. #827

• Prevent line wrapping on tables for programming exercises. #443

• IE/Edge browser compatibility features. #824

• Show video symbol on video panels. #814

• Hide learning outcomes within panel. #813

• Add URL redirects for Classic CS Unplugged URLs to new subdomain. #811

• Combine and update changelogs with Classic CS Unplugged. #820

• Update documentation on Verto ‘relative-link’ behaviour. #504

• Rewrite content style guide for external contributors. #791

• Add pre-requisite lesson for curriculum integrations. #366 #849

• Package updates:

  • Update django to 1.11.10.

  • Update verto to 0.7.3.

  • Update Pillow to 5.0.0.

  • Update yattag to 1.10.0.

  • Update django-modeltranslation to 0.12.2.

  • Update sphinx to 1.6.7.

  • Update django-extensions to 1.9.9.

  • Update coverage to 4.5.

  • Add django-haystack 2.6.1.

  • Add Whoosh 2.7.4.

  • Add django-widget-tweaks 1.4.1.

4.0.0-alpha.6.1

• Release date: 22nd December 2017

• Downloads: Source downloads are available on GitHub

Changelog:

• Fix bug where Cloud SQL Proxy searched for wrong credential file.

4.0.0-alpha.6

• Release date: 22nd December 2017

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release adds support for multiple languages, while also finalising the website design. New introductory pages and Pixel Painter resource have been added, and the ‘Unplugged Programming’ topic has been streamlined into the ‘Kidbots’ topic. Many other smaller corrections, illustrations, and bugfixes have also been added.

Changelog:

• Add support for multiple languages. #103

  • Automatically upload and download translations from Crowdin. #618 #619 #620 #621

  • Update website design for bidirectional langauges. #736

  • Implement dynamic text overlay for resource generation. #670

• Update website design

  • New navigation bar (with language picker).

  • New homepage design with card design for links. #698

  • Update topics index to show summary information. #696

  • Update resources index to use card design for links.

  • Simplify topic page. #696

  • Simplify unit plan page.

  • New footer design. #695

  • Update Bootstrap 4 from Alpha 6 to Beta 2.

  • Change header font to Sniglet and body font to Noto Sans.

• Add introductory pages on ‘What is Computer Science?’ and ‘How do I teach CS Unplugged?’.

• Restructure ‘Unplugged Programming’ to ‘Kidbots’ and remove duplicate lessons. #588

• Add Pixel Painter resource.

• Mention arrows resource in text. #702

• Restructure resource options to be generated from Python module. #701

• Add animations and illustrations for ‘The Great Treasure Hunt (Sorted)’ lessons. #672

• Add animations and illustrations for ‘Divide and Conquer’ lessons. #673

• Update Microsoft logo. #708

• Fix blank dropdown box in ‘Investigating variations using the Sorting Network’. #675

• Simplify ‘Error detection and correction’ logo.

• Modify csu helper script and Docker setup for OSX compatability. #651

• Package updates:

  • Add tinycss 0.4.

  • Add django-modeltranslation 0.12.1.

  • Add lxml 4.1.1.

  • Add uniseg 0.7.1.

  • Add python-bidi 0.4.0.

  • Add django-bidi-utils 1.0.

  • Update tqdm to 4.19.5.

  • Update django-debug-toolbar 1.9.1.

  • Update django-extensions 1.9.8.

  • Update coverage to 4.4.2

  • Update Django to 1.11.7 and lock Django to 1.11 versions (long term release). #679 #743

4.0.0-alpha.5

• Release date: 30th October 2017

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release improves many backend features, including smarter resource generation, dynamic resource previews, improved system testing, and bug fixes.

Changelog:

• Alter resources to use class based generators. #636

• Add resource thumbnails on generation page. #642

• Fix bug where production website is using development static files. #646

• Fix bug where production static files are not deployed.

4.0.0-alpha.4

• Release date: 17th October 2017

• Downloads: Source downloads are available on GitHub

Summary of changes:

Adds a new searching algorithms topic including lessons, resources, and curriculum integrations. New lessons for existing topics have also been added.

Changelog:

• Add searching algorithms topic. #548

• Add Unplugged Programming: Kidbots lesson 1 for ages 5 - 7. #549

• Add Unplugged Programming: Kidbots lesson 2 for ages 5 - 7. #550

• Add Unplugged Programming: Numeracy lesson 1 for ages 5 - 7. #551

• Add Sorting Network lesson 2 for ages 5 - 7. #595

• Add curriculum integrations for searching algorithms. #589

• Add 12 and 13 digit barcode checksum poster resources. #545 #546

• Add searching card resource. #547

• Update treasure hunt resource to include optional instruction sheet and colour version.

• Display alpha version number in header. #559

• Force HTTPS connection. #497

• Convert “Butterfly” and “Red Riding Hood” into sorting cards resource variants. #534 #535

• Update resources to new resource module specification.

• Allow raw HTML as source for resource generation.

• Use UCCSER Docker images for stability. #231

• Improve readability and efficiency of CSU helper script.

• Update Kidbots images to animations.

• Add video for Product Code Check Digits lesson.

• Update automated deployment infrastructure. #587 #590

• Add hover state for coloured panels. #591

• Fix bug where sorting network cards render incorrectly. #596

• Fix typo in 12-digit product code instructions. #599

• Open PDF resource download in new tab. #431

• Fix bug in Google analytics. #539

4.0.0-alpha.3

• Release date: 27th June 2017

• Downloads: Source downloads are available on GitHub

Summary of changes:

This release adds several lessons, curriculum integrations, and programming challenges. It also fixes many visual bugs and inconsistencies.

Changelog:

• Add Error correction and detection lesson 1 for ages 5 to 7. #487

• Move Computational Thinking links of Unplugged programming unit plans to separate files. #512

• Add Kidbots lesson 1 for ages 8 to 10. #514

• Increase size of content images. #516

• Fix images with wrong file extension. #517

• Add visual separators between units on topic page. #519

• Consistently name and capitalise unit plans. #520

• Add Sorting networks curriculum integration “Retelling a story”. #521

• Add Sorting networks curriculum integration “Growing into a butterfly”. #522

• Always display curriculum areas for learning outcomes on a new line. #523

• Center navbar menu text on mobile devices. #524

• Add modulo programming exercises. #525

• Set lesson tables to always be consistent width. #526

• Don’t show curriculum integrations shortcut in topic sidebar if no integrations are available. #533

4.0.0-alpha.2

• Release date: 26th June 2017

• Downloads: Source downloads are available on GitHub

Summary of changes:

The inital content for the Unplugged programming topic has been added which includes the geometry, numeracy, and Kidbots units.

Changelog:

• Add unplugged programming topic description. #469

• Add Kidbots unit plan. #470

• Add Kidbots lesson 3 for ages 5 to 7. #471

• Add job badges resource.

• Add left right cards resource.

• Add arrow cards resource.

• Add Kidbots programming exercises. #249

• Add geometry unit plan. #470

• Add geometry lessons 1 and 2 for ages 5 to 7. #495

• Add geometry programming exercises. #248

• Add numeracy unit plan. #470

• Add numeracy programming exercises. #247

• Add numeracy modulo lesson. #397

• Add sorting network lesson 1 for ages 5 to 7. #488

• Add binary numbers lesson 3 for ages 5 to 7. #486

• Update modulo clock to have blank option. #427

• Add trains straight and circular resources. #428

• Add piano keys resource. #429

• Add Google analytics. #496

• Fix links to deployments in README. #498

• Add “Try it out” programming challenge difficulty. #502

• Fix typo in how-binary-digits-work-junior lesson (thanks Richard S).`#503`_

• Fix Nginx build after Travis image update. #506

4.0.0-alpha.1

• Release date: 20th June 2017

• Downloads: Source downloads are available on GitHub

Summary of changes:

The first major step in releasing a open source version of CS Unplugged. While some existing content from the classic version of CS Unplugged have yet to be adapted into the new format and system, we are releasing this version as a sneak peek for teachers.

The backend system contains the following features:

• Open source system written in Django.

  • Allow translations of other languages (no translations are added yet).

  • Deployable on Google App Engine, and easily customised for other hosts.

• Website designed with Bootstrap 4 for use on all devices.

• Creates PDF resources for use with lessons.

• Basic test suite for checking system functionality.

• Documentation for the system.

The following topics are available in this version:

• Binary numbers:

  • 2 lessons for ages 5 to 7.

  • 3 lessons for ages 8 to 11.

  • 7 curriculum integrations.

  • 24 programming challenges.

• Error detetction and correction:

  • 2 lessons for ages 8 to 11.

  • 5 curriculum integrations.

  • 24 programming challenges.

• Sorting networks:

  • 1 lesson for ages 8 to 10.

3.2.2

• Release date: 11th January 2016

• Downloads: Word document

Changelog:

• Transcript of VP with chatbot reinstated in Turing Test material.

3.2.1

• Release date: 6th January 2016

• Downloads: Word document

Changelog:

• Two missing images (first example solution, and ladder networks) added to the Steiner trees activity.

3.2.0

• Release date: 5th January 2016

• Downloads: Word document

Changelog:

• Fixed some incorrect references to activity numbers caused by inserting a new activity.

• Some minor grammar/spelling corrections.

3.1.0

• Release date: March 2015

• Downloads: Word document and PDF document

Changelog:

• Switched to new logo design.

• Combination of the two parts into one book and introduces version numbering.

• Introduction updated.

• New activity added – Tablets of Stone.

• Minor updates to several activities and explanations.

• Improve Curriculum links (moving away from NZ Curriculum to general curriculum).

• Formatting improvements (fixing page numbers, layout, fonts changed – no more Comic Sans!).

• Fixed footers and copyright information to make creative commons license clearer.

2.5.0

• Release date: 2012

• Downloads: Part 1 Word document and Part 2 Word document

Changelog:

• Updated version of the teachers’ edition, including the remaining 8 activities from version 1.0.

• Updated a few terms that would no longer be meaningful to students e.g. mention of floppy disks.

2.0.0

• Release date: 2010

• Downloads: Word document

Changelog:

• The first 12 activities of the original version re-written by teachers in 1999/2000 so that it was more suitable for use in the classroom; minor changes were made through to 2010.

• This was eventually released as “open source” i.e. in MS Word, to support creating translations and local versions.

• Updated images and cartoons.

• Included links to the New Zealand curriculum.

1.0.0

• Release date: Mid 1990s

• Downloads: PDF document and LaTeX source

Changelog:

• Original version developed in the mid-1990s, with 20 activities, written by academics primarily for use as an outreach tool.