examples.md

Examples

The Processing website features a selection of code examples from the Processing software.

The source files for these featured examples are located in /content/examples. Before you contribute to the examples page, it is important that you understand where these files come from. In the context of the examples page, there are two kinds of files:

1. Files specific to the website (like the thumbnail, or the metadata). These files *should* be edited in this repository.
2. Files automatically copied from the processing-examples repo. These files should *not* be edited in this repository.

For instance, the files for Basic Examples > Image > BackgroundImage are located at:

/content/examples/Basics/Image/BackgroundImage/

That folder contains the following files:

File Path	Description	Edit here
BackgroundImage.json	Content file for the example (jump to section)	✅
BackgroundImage.png	Cover image used on page listings (jump to section)	✅
liveSketch.js	A manual port of the example to p5.js (jump to section)	✅
BackgroundImage.pde	Processing code for the example (code shown on the page)	❌

Additionally, if the original example had a Data folder, the contents of that folder are stored in /static/livesketch/. For BackgroundImage, you'll see a /static/livesketch/backgroundimage folder with a file called moonwalk.jpg. Do not edit this file ❌. Files in the /static/livesketch/ folder are copied from the processing-examples repo and should *not* be edited in this repository

Which file(s) should edit?

So you find an issue with an example on the website. Great! You are on your way to improving the Processing documentation and we are immensely grateful for your contribution! Here are the most common situations and the files you should edit.

Case 1: Issue with the live sketch

If the sketch running on the website doesn't work as it should, especially if it doesn't match the behavior of the Processing code shown on the page, then you should edit the livesketch.js in the corresponding example folder. The live sketch is a manual port of the Processing sketch to p5.js, created by a human. Do *not* try to edit the .pde file. That file is automatically copied from the processing-examples and does not run in a browser.

Case 2: Issue with the code sample

If there is a typo or any error in the code shown on an example page, head over to the processing-examples repository and create an issue describing the problem. You can also submit a pull request with a fix. Check the instructions below on bringing changes from processing-examples to this repo.

Updating examples via script

The Processing code for each example is copied via a script from the processing-examples repo to website. The script will do two things: It will copy all .pde files into the content/examples/TOPIC/SUBTOPIC/EXAMPLE folder and it will copy all files in the data folder of the example into a static/livesketch/EXAMPLE folder. This makes it possible for the liveSketch.js sketch to load the original data. Some live sketches differ slightly from the original example (such as the AlphaMask example requiring a .png file instead of a .jpg file) and these files are manually placed in the static/livesketch-manual folder.

Note: The script will only copy examples into the website that already have an existing .pde file. This means that the script will only update examples, not add new ones.

This is what you need to run the script:

1. Make sure that you have the processing-examples repo next to this processing-website repo on your computer
2. Pull the latest main from the processing-examples repository
3. From the root of this repo, run npm run updateExamples. The script will prompt you with an overview of the changes before it does anything.

You should now have the updated example files in your repo ready to be committed. Please submit the changes as a PR to the main branch of processing-website.

Adding a new example

When adding a new example, copy/paste an existing example folder and change the content of all files to reflect the example. Remember to put any files inside the data folder into /static/livesketch/EXAMPLE and write the liveSketch.js file to read from this folder.

Content file

Each example has to have a .json file in this format:

{
  "name": "",
  "title": "",
  "author": "",
  "description": "",
  "featured": ["", "", ""]
}

All empty "" should be filled with the information for that examples.

The name is the name that will go to the url and the title is the title of the example shown on the page. You can find the name, title, author and description in the comments of the pde files here.

Featured functions

This is a new feature of the example pages so you should choose no more than 6 functions that appear in the example (in the .pde files) and put them in the .json file in the "features" field. The name of the functions should be the same as the name of their .json files located in /content/references/translations/en.

Cover image

Each example has an image or animation that comes from P5.js code. The cover should be exported as a .png from the original p5.js code from here to a size of 1280px720 (keeping the same proportions than the original sketch). If the example doesn't have a p5.js file, then the upscaling has to be done from the .pde files from here. The naming of the image it's the same than the content file.

Live Sketch

Most examples include a livesketch.js file implemented in p5.js, designed to replicate the original Processing sketch's behavior as closely as possible. It allows the example to run in a browser. This file is not automatically generated but must be authored and updated by a contributor.

Structure of a Live Sketch

The code uses instance mode and is encapsulated in a runLiveSketch() function.

All p5.js functions and variables must be accessed using the s instance (e.g., s.createCanvas()).

function runLiveSketch(s) {
  s.setup = () => {
    s.createCanvas(640, 360);
    // Initialization code
  };

  s.draw = () => {
    // Drawing code
  };
}