URL-Arguments#

Overview#

URL arguments allow you to customize the WebTigerPython environment and to share programs by appending parameters to the URL. The arguments are written after ‘/#?’ followed by the desired parameters. To add multiple parameters, concatenate them with ‘&’. These arguments also work in iframes.

Because the arguments are placed in the hash (after #), they are never sent to the server.

Note

Older links that put the arguments in the query string (/?layout=...) are still supported for backwards compatibility, but new links should use the /#? form.

Example:

https://webtigerpython.ethz.ch/#?layout=[{“type”:[“Editor”,“Console”],“size”:20},“Canvas”]&hide_topbar=true

Share links created with Share Code with Link have the following structure:

https://webtigerpython.ethz.ch/#?fs=<encoded>&currentOpenFile=<path>&runFile=<path>&device=<device>&layout=<json>&...

or for projects cloned from a Git repository:

https://webtigerpython.ethz.ch/#?gitRepo=<url>&currentOpenFile=<path>&runFile=<path>&device=<device>&...

Parameters#

Settings#

All fields of the settings message of the iframe API can be used as URL arguments: lang, layout, hide_topbar, dark_mode, device, error_messages, cascade_input, debug_mode, breakpoints, tutorial_size, file_system_size, playground, tag and the deprecated vanilla_python. Their meaning and possible values are listed in Embed WTP as an iframe.

In the URL, the values are written as text:

  • Booleans are written as true / false

  • layout and breakpoints are written as JSON, e.g. breakpoints={"main.py":[2,5]}. The legacy form breakpoints=2,5 (for main.py) is still supported

  • error_messages is a comma separated list, e.g. error_messages=TigerPython

  • playground is the simulator environment as LZString compressed JSON (LZString.compressToEncodedURIComponent). It is only relevant when a device is set

Files and code#

Parameter

Description

fs

The whole file system (files and folders), see File system (fs)

gitRepo

URL of a Git repository whose files are imported, see Git repository (gitRepo)

currentOpenFile

Path of the file that is opened in the editor. Omitted if it is main.py

runFile

Path of the file that is pinned as run file (see Multi-File System)

filesystemSize

Width of the file system sidebar in percent (0 closes it). Currently only applied to gitRepo links, where it defaults to 20

prog

URL of a Python file that is downloaded and opened as main.py. The server has to allow cross-origin requests (CORS)

code

Legacy format for one or more text files, see Legacy code format

If several sources are given, gitRepo takes priority over fs, which takes priority over code.

Other#

Parameter

Description

load_python

load_python=false defers loading Python (Pyodide) until it is needed, which makes the page load faster

File system (fs)#

The fs parameter encodes the whole file system of a program. Share links created with the share button use this format.

  1. Create an object containing all files and folders. The keys of files are the file paths, the values are the contents. Text files are stored as strings, binary files (e.g. images) as { "b64": "<base64 data>" }. dirs lists all folders (so that empty folders are kept as well).

  2. Convert the object to a string using JSON.stringify.

  3. Compress the string with LZString using LZString.compressToEncodedURIComponent. The result can be used directly in the URL.

{
  "files": {
    "main.py": "from lib.helper import greet\ngreet()",
    "lib/helper.py": "def greet():\n    print('Hello')",
    "img/logo.png": { "b64": "iVBORw0KGgo..." }
  },
  "dirs": ["lib/", "img/"]
}

function encodeFiles(files, dirs = []) {
  const jsonString = JSON.stringify({ files: files, dirs: dirs }); // step 1 and 2
  return LZString.compressToEncodedURIComponent(jsonString); // step 3
}

const link =
  "https://webtigerpython.ethz.ch/#?fs=" + encodeFiles({ "main.py": "print('Hello')" });

Decoding reverses the steps: LZString.decompressFromEncodedURIComponent → JSON.parse → restore files and folders.

Caution

The uncompressed file system may be at most 500 kB, otherwise the share button refuses to create a link.

Git repository (gitRepo)#

Note

Git clone and gitRepo share links are currently only supported for repositories on GitHub. Public repositories on gitlab.com work as well, but only if the URL ends with .git (e.g. https://gitlab.com/user/repo.git). Other Git hosts (e.g. self-hosted GitLab, Codeberg / Gitea or Bitbucket) are not supported, because the browser blocks the requests (CORS). If an import fails, WTP falls back to an empty main.py.

For projects cloned from a Git repository, the share link contains the repository URL instead of the files:

gitRepo=<encodeURIComponent(repositoryUrl)>

When the link is opened, the files of the repository are imported (without Git tracking). If the repository is private, the user is asked for a GitHub Personal Access Token.

Note

Only the committed state of the repository is shared. Uncommitted local changes are not included in the link.

Legacy code format (code)#

Older links use the code parameter, which contains a list of files. It still works, also with multiple files and paths with folders (e.g. lib/helper.py), but it cannot store binary files or empty folders, so new links should use fs.

  1. Convert your files into a list of JavaScript objects containing the properties name and data.

  2. Convert the list to a string using JSON.stringify.

  3. Compress the string with LZString and encode it with Base64 (LZString.compressToBase64).

  4. Escape the result for the URL with encodeURIComponent.

function encodeInputCode(inputCode) {
  const codeObject = [{ name: "main.py", data: inputCode }]; // step 1
  const jsonString = JSON.stringify(codeObject); // step 2
  const base64compressed = LZString.compressToBase64(jsonString); // step 3
  return encodeURIComponent(base64compressed); // step 4
}

URL Generator#

The URL Generator creates customized URLs for the WebTigerPython environment. It provides options to configure:

  • Source: one of three options:

    • Code: Python code that is encoded as main.py in the fs parameter. The link and the preview are updated while you type.

    • Multiple files: Choose several files or a whole folder from your computer. Every selection is added to the files chosen before (a file with the same path is replaced), and each file can be removed again with the × next to it. They are encoded with their folder structure in the fs parameter; images and other binary files are included as well. The files are only read in your browser and are not uploaded anywhere. You can choose which file is open in the editor and which file is pinned as run file.

    • Git repository: The URL of a Git repository (gitRepo). Private repositories ask the user for a GitHub Personal Access Token on load. Optionally, the open file and the run file can be given as paths in the repository.

  • Language: The language of the user interface.

  • Dark Mode: Toggle dark mode to adjust the interface’s color scheme.

  • Hide Topbar: Hide the top bar to give the editor more space.

  • Device: Choose a device such as micro:bit, Calliope mini or Root Robot, or select “None” if not using a device.

  • Layout: Customize the layout by selecting a predefined layout or entering a custom layout manually. Options include Standard, Alternative Layout, No Canvas, Mobile, and Mobile No Canvas.

The generated URL reflects all selected options. You can use it to share your setup or as the src of an iframe. The preview below shows how the configured environment will appear.

Source

Code (main.py):

Language

Dark Mode

Hide Topbar

Device

Layout

Manual Layout:

Preview

The preview is updated automatically when you change an option.