While I don't like being sick and lying most of the time, I managed to submit my 4 PR's to electron's documentation by converting their API examples to a Fiddle one 😊 because I just couldn't do nothing.
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 electron/fiddle/pull/203). However, there are currently no examples!
The ElectronJS website currently has an open PR (electron/electronjs.org/pull/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 installedcd YOUR_FIDDLE_IN_DOCS_FOLDER
standard --fix
Folder structure
Add the contents of your Fiddle (main.js, renderer.js , and index.html but notpackage.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
[ ] Manage window state
[ ] Window events (blur and focus)
[ ] Create a frameless window
[ ] Handling window crashes and hangs
[ ] Relaunch window after the process crashes
[ ] Relaunch window after the process hangs
[ ] Menus
[ ] Customize menus
[ ] Create an application menu
[ ] Create a context menu
[ ] Keyboard shortcuts
[x] Register a global keyboard shortcut @yashints
#20466
Adds all the Use system dialogs:
✅ Open a file or directory
✅ Error dialog
✅ Information dialog
✅ Save dialog
examples from electron-api-demos into a runnable Fiddle example.
While I don't like being sick and lying most of the time, I managed to submit my 4 PR's to electron's documentation by converting their API examples to a Fiddle one 😊 because I just couldn't do nothing.
Find out more about how you can contribute here:
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, andindex.html.Motivation
electron-api-demosinto Fiddle-friendly examples is a big step into ultimately having API code samples available in the docs as runnable Fiddles.Current Progress
electron/electron repo(see electron/fiddle/pull/203). However, there are currently no examples!Task
We will be attempting to port over all of the
electron-api-demosexamples 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 theelectron-api-demosource 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.
Folder structure
Add the contents of your Fiddle (
main.js,renderer.js, andindex.htmlbut notpackage.json) into a new/docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]folder in your fork ofelectron/electronFor a handy graph on what category/section/demo mean:
PR requirements
masterbranch.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
And here are mine:
1:
Description of Change
Refs #20442
Adds the Menu Shortcuts example from
electron-api-demosinto a runnable Fiddle example.Checklist
standardlinter passesRelease Notes
notes: Added Menu Shortcuts example from
electron-api-demosinto a runnable Fiddle example.2:
Description of Change
Refs #20442
Adds the Customize Menu (Create an application menu and Create a context menu) example from electron-api-demos into a runnable Fiddle example.
Checklist
standardlinter passesRelease Notes
Notes: Added the Customize Menu (Create an application menu and Create a context menu) example from electron-api-demos into a runnable Fiddle example.
3:
Description of Change
Refs #20442
Adds the Drag and Drop files example from
electron-api-demosinto a runnable Fiddle example.Checklist
standardlinter passesRelease Notes
notes: Added the Drag and Drop files example from
electron-api-demosinto a runnable Fiddle example.4:
Description of Change
Refs #20442
Adds all the Use system dialogs:✅ Open a file or directory
✅ Error dialog
✅ Information dialog
✅ Save dialog
examples from
electron-api-demosinto a runnable Fiddle example.Checklist
standardlinter passesRelease Notes
Notes: Added the Use system dialogs example from
electron-api-demosinto a runnable Fiddle example.