diff --git a/sites/labs/public/assets/jnlp-screenshots/debug_mode_toggle.png b/sites/labs/public/assets/jnlp-screenshots/debug_mode_toggle.png new file mode 100644 index 000000000..72a2e66c2 Binary files /dev/null and b/sites/labs/public/assets/jnlp-screenshots/debug_mode_toggle.png differ diff --git a/sites/labs/public/assets/jnlp-screenshots/popup_advanced_settings.png b/sites/labs/public/assets/jnlp-screenshots/popup_advanced_settings.png new file mode 100644 index 000000000..357c8468d Binary files /dev/null and b/sites/labs/public/assets/jnlp-screenshots/popup_advanced_settings.png differ diff --git a/sites/labs/src/content/docs/cheerpj-jnlp-runner/04-guides/debug-builds.mdx b/sites/labs/src/content/docs/cheerpj-jnlp-runner/04-guides/debug-builds.mdx new file mode 100644 index 000000000..fb53f30fb --- /dev/null +++ b/sites/labs/src/content/docs/cheerpj-jnlp-runner/04-guides/debug-builds.mdx @@ -0,0 +1,74 @@ +--- +title: How to debug the extension +description: How to enable debug mode and collect logs for troubleshooting +--- + +If you encounter issues while running a Java Web Start application with CheerpJ JNLP Runner, enabling **Debug Mode** can provide detailed logs that help our support team identify the problem. + +## Verifying the Extension is Working + +Before enabling debug mode, let's verify if the extension is active and properly handling JNLP files: + +- **Is the extension pinned?** Ensure the CheerpJ JNLP Runner is pinned to your browser's toolbar so you can easily access it. +- **Is the extension enabled?** Check your browser's extensions page (`chrome://extensions` or `edge://extensions`) to confirm it is toggled on. +- **Are you using the correct extension?** Make sure you have the CheerpJ JNLP Runner installed (not the Applet Runner). +- **Does the application launch?** When you click a `.jnlp` link, the application should start automatically, with the extension side panel on the left side of the screen. +- **Did the JNLP file download instead?** If your browser downloads the `.jnlp` file instead of launching the application, you can use **drag and drop** to test it—simply drag the downloaded file into the extension popup. +- **Are there any Network errors?** Open the browser's developer tools and check the Network tab for failing requests. +- **Are you seeing startup or socket errors?** If the application fails during startup, or reports errors when opening network (socket) connections, please reach out to us on our [Discord server](https://discord.leaningtech.com/) for further assistance. + +If everything above is functioning correctly but you are still experiencing issues, please reach out to us on our [Discord server](https://discord.leaningtech.com/) or by opening an issue on our [GitHub repository](https://github.com/leaningtech/cheerpj-jnlp-runner/issues) so we can assist you. To help us troubleshoot, please enable debug mode as described below and provide the resulting logs. + +## Enabling Debug Mode + +To enable the debug build of CheerpJ: + +1. Click the **CheerpJ JNLP Runner icon** in your browser's toolbar, then click **Advanced Settings** in the popup. + +
+ ![Extension popup showing the Advanced Settings + button](/assets/jnlp-screenshots/popup_advanced_settings.png) +
+ +2. Under **General**, toggle **Debug Mode (Slow)** to **On**. + +
+ ![Advanced Settings page showing the Debug Mode (Slow) toggle in the ON + position](/assets/jnlp-screenshots/debug_mode_toggle.png) +
+ +3. The extension will now use the debug version of the runtime, which includes extensive logging but runs more slowly. + +> [!important] Reload Required +> You must enable the debugging mode **before** loading your application, or **reload the page** after enabling it. Otherwise, the setting will not take effect. + +## Collecting Debug Information + +To help us troubleshoot, we typically need two files: the **Console log** and a **Network HAR file**. + +### Step 1: Open Browser DevTools + +To ensure we receive complete logs, **you must reload the page after opening the developer tools**. + +1. Press `F12` (Windows/Linux) or `Cmd + Opt + I` (Mac) to open the DevTools. +2. Alternatively, right-click anywhere on the page and select **Inspect**. + +### Step 2: Save the Browser Console Output + +1. With the developer tools open, navigate to the **Console** tab. (If you don’t see it, click the `+` symbol in Edge or `>>` in Chrome, then select Console). +2. If needed, trigger the error in your application. +3. Right-click on any message in the console tab and select **Save as…** +4. Save the console log to a file. + +### Step 3: Extract a HAR File + +A HAR (HTTP Archive) file logs your browser's network interactions and helps us diagnose loading or server responses. + +1. In the developer tools, navigate to the **Network** tab. +2. **Reload your page** to ensure the network log captures requests from the very beginning. +3. Trigger the error in your application if needed. +4. Click the download icon (`↓`) at the top right of the Network tab to export and save the HAR file. + +--- + +Once you have collected these files, please attach them to your support request or bug report on our [Discord server](https://discord.leaningtech.com/) or [GitHub repository](https://github.com/leaningtech/cheerpj-jnlp-runner/issues). diff --git a/sites/labs/src/content/docs/cheerpj-jnlp-runner/04-guides/file-handling.mdx b/sites/labs/src/content/docs/cheerpj-jnlp-runner/04-guides/file-handling.mdx new file mode 100644 index 000000000..e65b7ca63 --- /dev/null +++ b/sites/labs/src/content/docs/cheerpj-jnlp-runner/04-guides/file-handling.mdx @@ -0,0 +1,42 @@ +--- +title: Upload and download files +description: How to interact with the local filesystem using the JNLP Runner extension +--- + +For a deeper dive into how file systems work in CheerpJ, check out the [File System explanation guide](https://cheerpj.com/docs/explanation/File-System-support). + +The CheerpJ JNLP Runner extension provides a virtual filesystem that allows Java Web Start applications to read and write files within the browser's sandbox. Since browsers cannot access your local disk directly for security reasons, CheerpJ provides two main ways to move files into and out of this virtual space. + +## Uploading files + +To import a file from your local machine to the virtual filesystem, you can use either the built-in file picker or the extension side panel. In both cases, the files will be placed in the **`/files/uploads/`** virtual directory. Inside the Java application, you can navigate to `/files/uploads/` to open or use these files. + +**Using the built-in file picker:** + +The upload icon (an upward arrow) is present as part of the title bar on any Java window, frame, or File Dialog that opens. + +1. Click the **upload icon** in the title bar. +2. Select a file from your local file system (your machine). +3. In the File Dialog, navigate to `/files/uploads/` and select the file to load it into the application. + +**Using the extension side panel:** + +Alternatively, you can upload files directly from the extension side panel that appears on the left side of the screen while an application is running. + +1. Ensure the Java application is currently running. +2. Hover over the side panel to expand it and click **Upload file**. + +
+ ![Extension side panel expanded next to a running application, showing the + Upload file option](/assets/jnlp-screenshots/jnlp_sidepanel.png) +
+ +3. Select the file(s) from your local filesystem. + +## Downloading files + +To export data from the Java application back to your local machine, simply ensure files within the application are saved to the **`/files/downloads/`** virtual directory. Any file saved to this directory will be automatically detected and downloaded by your browser to your local machine (usually to your default Downloads folder). + +**Using a standard save dialog:** + +If you use a "Save" File Dialog and choose a path under **`/files/downloads/`**, the browser will automatically trigger a download once the save operation is complete.