# Examples

The Processing website features [a selection of code examples](https://processing.org/examples) from the Processing software.

The source files for these featured examples are located in `/content/examples`. Before you contribute to the [examples](https://processing.org/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.
1. Files automatically copied from the [`processing-examples`](https://github.com/processing/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](#content-file))                                 | ✅        |
| `BackgroundImage.png`    | Cover image used on page listings ([jump to section](#cover-image))                            | ✅        |
| `liveSketch.js`          | A manual port of the example to p5.js ([jump to section](#live-sketch))  | ✅        |
| `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`](https://github.com/processing/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`](https://github.com/processing/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`](https://github.com/processing/processing-examples) repository and [create an issue](https://github.com/processing/processing-examples/issues) describing the problem. You can also submit a pull request with a fix. Check the instructions below on bringing changes from [`processing-examples`](https://github.com/processing/processing-examples) to this repo.

## Updating examples via script

The Processing code for each example is copied via a script from the [`processing-examples`](https://github.com/processing/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
1. Pull the latest `main` from the `processing-examples` repository
1. 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](https://github.com/processing/processing-docs/tree/master/content/examples).

### 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](https://github.com/processing/processing-docs/tree/master/content/examples_p5) 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](https://github.com/processing/processing-docs/tree/master/content/examples). 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()`).

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

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