loading...

re: Hacktoberfest Completion Thread VIEW POST

FULL DISCUSSION
 

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:

[Hacktoberfest] Porting electron-api-demos to Electron Fiddle examples in docs #20442

erickzhao avatar
erickzhao commented on Oct 05, 2019

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 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 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
      • [ ] 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
  • [ ] Native User Interface
    • [ ] Open external links and the file manager
      • [ ] Open path in file manager
      • [ ] Open external links
    • [ ] Desktop notifications
      • [ ] Basic notification
      • [ ] Notification with image
    • [ ] Use system dialogs
      • [ ] Open a file or directory
      • [ ] Error dialog
      • [ ] Information dialog
      • [ ] Save dialog
    • [ ] Tray
      • [ ] Tray
    • [ ] Drag and drop files
      • [ ] Dragging files
  • [ ] Communication
    • [ ] Communicate between processes
      • [x] Asynchronous messages @erickzhao #20441
      • [x] Synchronous messages @97amarnathk #20451
      • [ ] Communicate with an invisible window
  • [ ] System
    • [ ] Get app or user system information
      • [ ] Get app information
      • [ ] Get version information
      • [ ] Get system information
      • [ ] Get screen information
    • [x] Clipboard @RikTheunis @#20445
      • [x] Copy
      • [x] Paste
    • [ ] Protocol Handler
      • [ ] Launch app from URL in another app
  • [ ] Media
    • [ ] Take screenshot
      • [ ] Take a screenshot

And here are mine:

1:

docs: add Menu Shortcuts Fiddle example #20466

yashints avatar
yashints commented on Oct 08, 2019

Description of Change

Refs #20442

Adds the Menu Shortcuts example from electron-api-demos into a runnable Fiddle example.

Checklist

  • [x] PR description included and stakeholders cc'd
  • [x] standard linter passes
  • [x] PR title follows semantic commit guidelines

Release Notes

notes: Added Menu Shortcuts example from electron-api-demos into a runnable Fiddle example.

2:

docs: Adds Customize Menu section Fiddle example #20468

yashints avatar
yashints commented on Oct 08, 2019

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

Release 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:

docs: Added Drag and drop files Fiddle example #20472

yashints avatar
yashints commented on Oct 08, 2019

Description of Change

Refs #20442

Adds the Drag and Drop files example from electron-api-demos into a runnable Fiddle example.

Checklist

  • [x] PR description included and stakeholders cc'd
  • [x] standard linter passes
  • [x] PR title follows semantic commit guidelines

Release Notes

notes: Added the Drag and Drop files example from electron-api-demos into a runnable Fiddle example.

4:

docs: Adds Use system dialogs Fiddle example #20473

yashints avatar
yashints commented on Oct 08, 2019

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-demos into a runnable Fiddle example.

Checklist

  • [x] PR description included and stakeholders cc'd
  • [x] standard linter passes
  • [x] PR title follows semantic commit guidelines

Release Notes

Notes: Added the Use system dialogs example from electron-api-demos into a runnable Fiddle example.

code of conduct - report abuse