Porting electron-api-demos to Electron Fiddle examples in docs

[erickzhao]

Context

This meta-issue addresses a need to bridge the gap between our website's online docs, electron-api-demos, and Electron Fiddle.

• What's electron-api-demos?

  As the name indicates, electron-api-demos` is a collection of examples for Electron APIs wrapped in an application. Each demo contains a executable example of the API along with sample code and additional explanations.

• What's Electron Fiddle?

  Electron Fiddle is a code playground allowing developers to tinker around with small experiments that can later be exported into full-fledged Electron applications. The interface allows users to create and run small Electron apps with a single main.js, renderer.js, and index.html.

• Motivation

  • Although collecting runnable API demos is nice, having the sample code gated behind an application increases friction, and maintaining the app in its current state for more than 1 release line is difficult.
  • Having the code available online makes it easier to find and more accessible to read, but having to manually launch
  • Porting over electron-api-demos into Fiddle-friendly examples is a big step into ultimately having API code samples available in the docs as runnable Fiddles.
• Current Progress

  • Recently, Electron Fiddle added the capability of loading code directly from the docs on the electron/electron repo (see feat: add support for launch examples from the Electron docs fiddle#203). However, there are currently no examples!
  • The ElectronJS website currently has an open PR (feat: add 'Launch in Fiddle' button to code blocks electronjs.org-old#2848]) adding the ability to launch the Fiddle protocol from the Electron website.

Task

We will be attempting to port over all of the electron-api-demos examples in the codebase. For context on how API demos are structured, see the docs here.

The task is to ultimately convert each demo into an Electron Fiddle sample that's equivalent in functionality. Please include the explanatory text from the HTML files as well. Note that many of these demos are tightly coupled in logic, and a single PR can be submitted for multiple demos within a Section.

The easiest way to do so is to pick an example in electron-api-demos, recreate the example in Electron Fiddle (using the electron-api-demo source code as a starting point), save the Fiddle locally into a folder, and move that example into /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO].

Example Fiddle

See the following PR for an example of this task (Asynchronous Messages demo): #20441

Code style

Code should follow the StandardJS style guidelines. To format your code, run the following snippet in your directory.

    npm install -g standard # if you don't have it installed
    cd YOUR_FIDDLE_IN_DOCS_FOLDER
    standard --fix

Folder structure

Add the contents of your Fiddle (main.js, renderer.js , and index.html but not package.json) into a new /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO] folder in your fork of electron/electron

For a handy graph on what category/section/demo mean:

PR requirements

• PR is merging into master branch.
• File structure adheres to the requirements above.
• Code in PR runs successfully in Electron Fiddle with the latest release of Electron 6.
• Code in PR passes a linting check with Standard.

Assignees

Since this is a meta-issue that will require many PRs from contributors, we will attempt to proceed in a first-come-first-serve fashion. Examples will be marked as claimed as soon as a PR is opened for them.

In the interest of focusing on getting each PR reviewed and merged, please only open one PR at a time before opening another.

List of Demos

• Windows
  • Create and manage windows
    • Create a new window @wedob13 docs: New fiddle example 'Create a new window' #20480
    • Manage window state
    • Window events (blur and focus)
    • Create a frameless window @kristofkalocsai docs: added windows -> create frameless window example #20591
  • Handling window crashes and hangs
    • Relaunch window after the process crashes @ValerianClerc docs: New fiddle example 'Window Crash' #20571
    • Relaunch window after the process hangs
• Menus
  • Customize menus @yashints docs: Adds Customize Menu section Fiddle example #20468
    • Create an application menu
    • Create a context menu
  • Keyboard shortcuts
    • Register a global keyboard shortcut @yashints docs: add Menu Shortcuts Fiddle example #20466
• Native User Interface
  • Open external links and the file manager
    • Open path in file manager @kristofkalocsai docs: Added Native User Interface -> Open path in file manager Fiddle example #20589
    • Open external links @alanionita feat: #20442 adds fiddle for opening external links... #20763
  • Desktop notifications @harryi3t docs: add notification examples #20528
    • Basic notification
    • Notification with image
  • Use system dialogs @yashints docs: Adds Use system dialogs Fiddle example #20473
    • Open a file or directory
    • Error dialog
    • Information dialog
    • Save dialog
  • Tray
    • Tray
  • Drag and drop files
    • Dragging files @yashints docs: Added Drag and drop files Fiddle example #20472
• Communication
  • Communicate between processes
    • Asynchronous messages @erickzhao docs: add Asynchronous Messages Fiddle example #20441
    • Synchronous messages @97amarnathk docs: add Synchronous Messages Fiddle example #20451
    • Communicate with an invisible window
• System
  • Get app or user system information
    • Get app information @97amarnathk docs: add app information example #20487
    • Get version information @RikTheunis docs: add system get version info Fiddle example #20536
    • Get system information @jh3y docs: add fiddle for get system information #20662
    • Get screen information
  • Clipboard @RikTheunis docs: add clipboard Fiddle examples #20445
    • Copy
    • Paste
  • Protocol Handler
    • Launch app from URL in another app @alanionita feat: adds the fiddle for launching an app from URL #20442 #20718
• Media
  • Take screenshot
    • Take a screenshot @harryi3t docs: add example for taking screenshot #20531

---

[97amarnathk]

I would like to work on this. Can this be assigned to me?

[erickzhao]

I would like to work on this. Can this be assigned to me?

@97amarnathk Feel free to submit a PR for any demo (see #20441 for an example). I'll keep the meta-issue with assignees as the PRs flow in.

[97amarnathk]

@erickzhao Where do I find the HTML files related to synchronous communication?

[erickzhao]

@erickzhao Where do I find the HTML files related to synchronous communication?

@97amarnathk You can find all relevant HTML files included in the sections folder of electron-api-demos. For the case of synchronous communications, find the file under sections/communications/ipc.html.

For more info on how electron-api-demos is structured, see this design doc: https://github.com/electron/electron-api-demos/blob/master/docs.md

[97amarnathk]

@erickzhao I have submitted #20451 for Synchronous Messages.

[yashints]

Hey @erickzhao, had a question for you. I am working on adding the manage window section in which the renderer is referencing a local html file by path (modal.html). I can't add additional files to Fiddle to be referenced. What's the workaround?

[wedob13]

@erickzhao I have submitted #20480 for 'Create a new Window' i can grab another one as soon as this pull gets merged.

Thanks for checking it out :)

[97amarnathk]

@erickzhao I added a PR for getting app info.
#20487

[harryi3t]

@ericbrumer Raised PR for context menu
#20506

Also, didn't find any view demo button for application menu, it's just static code. Wanted to cover that too in the same PR 🙂

[yashints]

@ericbrumer Raised PR for context menu
#20506

Also, didn't find any view demo button for application menu, it's just static code. Wanted to cover that too in the same PR 🙂

Hmmm 👉🏼#20468

[harryi3t]

Hey @yashints,
Sorry didn't see that there was already a PR. The description said that the items would be checked off when someone raises a PR for them

Examples will be marked as claimed as soon as a PR is opened for them.

I will close my PR and I guess I would have to go through all the linked PRs to get an idea of what's already taken.

[erickzhao]

Sorry for the confusion, will update the list ASAP and get to reviewing some PRs today :)

[97amarnathk]

@erickzhao , I provided a PR for app information and not clipboard. Could you update the Issue description accordingly?

[yashints]

@erickzhao I need to find out how to include assets (icons, templates, etc) in Fiddle examples, any hints?

[erickzhao]

I need to find out how to include assets (icons, templates, etc) in Fiddle examples, any hints?

@yashints Previous patterns simply generated the image from the Data URL

See: https://github.com/electron/fiddle/blob/master/static/show-me/tray/main.js

[yashints]

Thanks, what about html templates? like modals

[erickzhao]

@yashints I talked about this a bit in the Create Window PR, but as a solution, loading an external URL (e.g. https://electronjs.org) could be a standby for loading an HTML partial.

[yashints]

NP, I will create my PR with an external link then

[wedob13]

@erickzhao is it okay if i get started on another pull or should i wait for my previous one to be reviewed?

[erickzhao]

@wedob13 I'd say to go for it! I've been lagging behind on reviewing the PRs lately.

[erickzhao]

This is pretty much done in 2022 :)