electron / electron-api-demos Goto Github PK

Explore the Electron APIs

Home Page: http://electronjs.org/#get-started

License: MIT License

CSS 12.57% HTML 51.79% JavaScript 33.92% Shell 1.72%

electron-api-demos's Introduction

Electron API Demos

This is a desktop app that interactively and with sample code demonstrates core features of the Electron API. It's built with Electron, too, of course. This app works on Windows, macOS and Linux operating systems.

Use this app to see what you can do with Electron and use the source code to learn how to create a basic Electron app.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Follow @ElectronJS on Twitter for important announcements. Visit the electron website.

Using

You can download the latest release for your operating system or build it yourself (see below).

Building

You'll need Node.js installed on your computer in order to build this app.

$ git clone https://github.com/electron/electron-api-demos
$ cd electron-api-demos
$ npm install
$ npm start

If you don't wish to clone, you can download the source code.

For easier developing you can launch the app in fullscreen with DevTools open:

$ npm run dev

Extending

Read the docs to learn more about how this app is built or how to add a new demo.

Translations

Simplified Chinese translation of this app is available at demopark/electron-api-demos-Zh_CN.
Traditional Chinese translation of this app is available at CalvertYang/electron-api-demos-zh-Hant.
Japanese translation of this app is available at LeeDDHH/electron-api-demos-ja.

Note: these versions are maintained by outside contributors and may not always be in sync with this version.

electron-api-demos's People

Contributors

Stargazers

Watchers

Forkers

punker76 jasonjensen nairinarinyan fiveminuteargument erodewald lawrenceue divyam8 bheliom joshburgess atouhou killavus rongfengliang semperos poyhsiao ozkrleal rlugojr tai-fukaya heivin waifei maarekj bradparks shubhamtotala bsletten narayanapk ariesw f3r eydunn luisbrito kilian vacjaliu matjaz iyedb 7azycoder christianmarchiori ingorichter rockyspade agt7 djgraham fengweijp adon988 zhhb itflypig sandeepnegi forkedorg gitname clevekim00 liquanchun xin2893 andywangjun maolala aranguren eeyoo hostenvoy robbenbasten sky7sea grantges victorv2k zackhaikal duanshuaimin kevinsuttle lovewalter ajpo-electron amulyayadavilli invstgit robic levysn m0k1 basictechy rpampatiaxio samyk jango2015 urmyfaith quartzing openube jonham totoyer mygeneralelectric donflopez ryanlane am1102 newtonguo simonkern imzzy vrdate di445 timlgy aaroncao abdihaikal gamain huanjiesm yusiwen pkdevboxy morganhancock minhkhanb abacram amilajack allin09 adrienjoly sandboxed-forks ghhv

electron-api-demos's Issues

Quality Control Check List

Various things to not forget about:

Add an installer loading gif?

Squirrel installers allow for a loading gif.

Currently it is configured to use: https://github.com/electron/electron-api-demos/blob/master/assets/img/loading.gif

We don't necessarily need an animated one but I wanted to see if people thought we needed something more than the current one.

For comparison, Atom uses this:

/cc @simurai

Development To Do List

These are development tasks to be done in the app:

Windows icon

I've packaged it up and tried it out on Windows and the icon looks great except for in the bottom toolbar (what is that called?) it seems a little pixelated. I opened up Atom to compare and it definitely looks crisper.

Looking great—

APIs that don't have demos yet

This list is an attempt to gather all the APIs listed at https://github.com/atom/electron/tree/master/docs/api that don't yet have a corresponding demo:

In Process

accelerator (keyboard shortcuts)
- 🚧 #131
global-shortcut
- 🚧 We could set a global shortcut to the menu item we create for the menu demo?

Hard to demo or wouldn't be very valuable.

Done

Perhaps we should filter and prioritize this list, then get to as many as we can in time for the 1.0 launch.

OS Menu Item Naming Conventions

I was thinking of having a pro tip on the menus page about different naming conventions for menu items on different OSes. Like Preferences : Settings for OS X : Win.

Our docs have some OS X tips but not a table like this so I'm trying to pick y'alls brains:

—Are there enough of these to warrant a pro-tip?
—If there are enough, what are they?
—If not this as a pro tip, any other menu pro tip ideas?

/cc @kevinsawicki @zcbenz and @amytruong because you visit Windowsland.

New App icon?

Hey.. I'm still not too happy with the app icon. There isn't a big connection to the app itself. And the dark green doesn't look that friendly.. so how about this:

It's made of the 6 colors used for the sections and similar to the About graphic.

Support auto-updates before 1.0 launch

@jlord pointed out that once we open-source this app, we'll likely be getting contributions from the community. It would be aweome if the demo app we release on launch day is able to update itself automatically, so anyone who has ever downloaded it will always have an up-to-date version.

@kevinsawicki we would need your help on this one!

Language

I'm going to jot down notes here of questions around language and phrasing that I have as I'm going through this.

You can create : Create
your app : an app
native : operating system (in re: to readability for beginners)
renderer

Turn ProTips™ into regular tasks

On our 1:1 call today, @jlord and I decided to do away with the pro-tips in the app, and instead use "tasks" for everything. This will make the UI less busy and the codebase more consistent.

The extant tips, as of today:

run background tasks
OS menu differences
open outbound links externally
sheet dialog for os x
tray support in linux
Find versions of Chromium Node.js V8
Use a print stylesheet

Pairing with the Quick Start App

What are the ways we can give the Quick Start App more ⨫ synergy ⨬ with the Demo App?

(many of these changes will happen in the quick start app but since that one is open/public right now I felt it better to talk it through over here)

Add comments to code like / place your main process code here
Link to a starter render process js file from index.html

Windows

I'm starting to test out the app in Windows (8) and will keep track of bugs here:

Print to PDF fails
Open file manager does nothing with no errors
Font isn't rendered in window demo
Move window demo just flickers

Windows Screenshot

Text Pileup on Section Change

On master when I click to change sections in the sidebar I'm getting this text pileup:

I think the gif removes some frames which makes it appear like it doesn't happen at every click, but it does.

cc @simurai

Set up Auto Update

So that this app auto updates ✨

Terminology

@jlord and I just had a quick call to give formal names to various parts of the app's UI hierarchy. We ended up with Category > Section > Demo. This is not currently reflected in HTML and CSS class names, but maybe we can gradually move towards it as we continue developing.

Add Packaging Scripts

It's almost that time! I need to set up the packaging npm scripts 📦

🔗 #49

Cookbook!

@simurai and I chatted today about keeping this app away from pure documentation styles, to make it more of a story, more about... recipes.

He shared this cookbook that he worked on previously which is similar. It shares examples for how to do x, y, z.

I like this though I think the word "cookbook" feels odd paired with "Electron" and isn't commonly used enough that people would get it. But maybe there is a science-y, space-y word that is similar that would work better?

blueprint
formula
mode
procedure
manual (!?)

Tray demo is busted

It was working recently. Not sure what regressed.

CSS Normalizing for Electron Demo App (and Beyond)

We talked (at mini-summit) about potentially creating CSS that Electron app builders could include in order to give them a starting point for making their Electron app feel more native and not website-y.

I'd like to do at least some level of this for the demo app (it could later be expanded on and moved into its own repo to accomplish ☝️). It would be awesome to 🍐 some with you @simurai on this. Do you have time in the next couple of weeks to work on this?

Set up Travis

So that we have our tests run with Travis ✨

External Links Style

@simurai how do you feel about using a small octicon along side external links to signal that they are external? I think I like it, but I defer to you!

I have a quick mock up of it on exlinks branch.

Accessibility

Before we launch lets cover the bases with accessibility to set a good example and to help us better document anything we come across during the process.

Self-assigning but happy to 🍐 I'll be pinging @maun a lot on this 😄

Write main process code as you would in a normal app

In order to automate the runtime setup of this demo, each demo's main process code is wrapped in a module.exports function:

var ipc = require('electron').ipcMain
var dialog = require('electron').dialog

module.exports.setup = function () {
  ipc.on('open-error-dialog', function (event) {
    dialog.showErrorBox('An Error Message', 'Demonstrating an error message.')
  })
}

Then each file is required and its function invoked:

// Require and setup each JS file in the main-process dir
glob(__dirname + '/main-process/**/*.js', function (error, files) {
  if (error) return console.log(error)
  files.forEach(function (file) {
    require(file).setup()
  })
})

However, most users wouldn't write an electron app this way. They would just write:

var ipc = require('electron').ipcMain
var dialog = require('electron').dialog

ipc.on('open-error-dialog', function (event) {
  dialog.showErrorBox('An Error Message', 'Demonstrating an error message.')
})

It would be great if we could write the main process files as a user would, then figure out a way to eval them at runtime. Something like this:

// Require and setup each JS file in the main-process dir
glob(__dirname + '/main-process/**/*.js', function (error, files) {
  if (error) return console.log(error)
  files.forEach(function (file) {
    eval(fs.readFileSync(file, 'utf8'))
  })
})

Add an intro section about the quickstart app

@jlord and I are thinking it would be good for demo users to use electron-quick-start as their sandbox app while working through the demo. We should add an introductory section that covers the basics of getting the app up and running:

git clone https://github.com/atom/electron-quick-start
cd electron-quick-start
atom .
npm install
npm start

Might wanna also mention that git and node are required. We could use https://github.com/jlord/git-it-electron as a starting point for that content. I like that it recommends using GitHub Desktop as a simple way to install git.

Structure, a different take

I've been thinking about this and sketching out how this may all be laid out and I am thinking rather than present it as just documentation that you can click on, that it can be structured by what you can do with Electron and in human-speak. Rather than needing to guess and search for the module name that you need, you can learn by wha you want to do.

So, for instance, the main view would pose these topics in bold sections, Do you want to:

Create a new window
- New window
- New web view
- New hidden window
- New frameless window
Use native dialogs
- alerts
- information
- open file
- save file
- sheet style & default dialogs
Creating Shortcuts
- Create global shortcut
Communicate with another process
- Create custom ipc message
- Use remote in renderer process
Build a menu
- Native menu
- Context menu
Find out info on the app, or user’s system
- Version of Electron, name path locale
- Stuff from process, or os module
  -Things in http://electron.atom.io/docs/v0.34.0/api/screen/
Open external links or window manager
- Open external links
- Open window manager
Using the tray icon
Using the clipboard
Managing window state
- Managing recent documents
- Dealing with modified files (window state to edited)
- Demo showing all the events (focus, blur, min, max, resize, move, etc)
- Programmatically changing the window (size, position, etc)
Printing to PDF

The Guides section is one that can come after shipping the rest of the app and doesn't contain demos per say but rather best practices and tips.

Each of these (and there can be more) can be grouped/colored by category:

Native UIs
Process Communication
System Information
Packaging

Each page, would demo the APIs and link to the code of the app (I've gone back and forth on if the code snippet should also be shown, but it seems hard to maintain this way should to app code change, then the sample code has to be too)

There would be some shared UI elements within each page:

Pro Tip
OS support labels

This is just an initial brain dump based on the stuff I've been experimenting with and I'll likely update/refine it as I keep working on it.

Navigation

I'm not sure anymore about the navigation. I think it's fine if you try to find something, but if you try to look at each demo, one by one, it takes some effort to:

scroll up
click the back button
scroll to the next item (since it doesn't keep previous scroll position)
click on next item

So maybe at the bottom of each "page", there could be a "next" button to keep going forward and not having to go back all the time.

Add Chrome Accessibility DevTools Extension

This is related to #121 but specifically about trying to get the Chrome Accessibility DevTools Extension working here (and in Electron).

Electron apps are websites in a sense, but not in the sense that they have urls that can use be used with online accessibility auditors. Getting this devtools extension working would be really helpful for Electron app developers in making their apps accessible to more people.

Not all of the chrome.* APIs have been implemented so we need to compare what this extension uses against what is currently implemented, then we'll see how far we have to go.

🍐 with @kevinsawicki

Get list of chrome.* APIs used in extension #126 (comment)
Get list of currently implemented chrome.* APIs

Manage window state demo window jumps back to place higher than it started

Before:

After:

Add app to start menu on Windows

During the installer run we should add the app to the start menu.

Tone down the external links

I find the current external link treatment a bit distracting and out of sync with the color scheme. @jlord and @simurai: What do you think of just using underlines and desaturating the external link image?

Before:

After:

Display Copy/Paste Shortcuts in Clipboard Demo

Putting this in its own issue, ported from #81—

Detect the user's OS with process.version and only display one of: (CMD + V or CTRL + V)

Update Specs for last active section/demo

First, to figure out how the app that runs in the specs is even storing this 😀

Linux

I'm taking the app for a spin in Linux (Ubuntu 12.04.5 LTS) and making some notes here.

No tray icon (and no error) #42
- Get Gtk-Message: Failed to load module "unity-gtk-module" message on startup (console)
PDF doesn't open because my system doesn't have a default viewer 796a714

Style cleanup

Reminder to self: At some point I probably should go through all the styles and do some cleanup/refactoring.

Things like this: https://github.com/atom/electron-api-demos/blob/master/assets/css/content.css#L297-L299

Closing Old Windows

If you do one of the demos that creates a new window and then you don't close that new window and you at some point refresh the app and then decide to close the window, you get an error:

Not sure what best practice is for handling this.

App icon

Did we settle on the name "Electron Demos"? See #3

If so, we could have an icon in a shape of a big D. Like

Welcome Page

I want to create an about/welcome page that is the first page people see when they open the app.

This page will be brief but explain a little about what the app is and how to use it. 🍕

CI

Should we set it up on this repo?

Welcome illustration?

Should we add some kind of fun/friendly illustration on the welcome page? No idea what.. but just to illustrate here is Inspectocat:

Or is that too cheesy. It doesn't have to be an Octocat, or maybe more subtle. Just to give it a tiny bit more recognizability and fill the empty space.

Structure

This app will be lightweight, a few pages based on Electron API categories, which demonstrate the API.

Index
Main process modules
Render process modules
Shared modules
Custom DOM elements

A lot of will be figured out as this is put together, like perhaps each module has its own page and perhaps there is a page explaining the two process types. And likely some static site generating happening, too.

Introduce ES2015 features used in the demo

A followup to #79

To quote @lee-dohm

So it sounds like there are multiple potential groups that have conflicting sets of things that are "unclear". Could we use this as an opportunity to educate people? Perhaps for anything that isn't typical ES5 (or anything we want/have to use that we feel might be confusing to one camp or another) we have a section in the demo for, "Hey, what's this strange syntax?" with links to relevant documentation?

@jlord and I discussed this today and decided we should preface the demo with a blurb about electron's support for ES2015, and cover the specific new language features that will be used throughout the demo app: template strings, const, and let.

Code Scrolling

I can't horizontally scroll in the code blocks. It's super weird because when I open DevTools and toggle off and then back on the overflow and overflow-x properties of .hljs and pre, then it works. Even though it's returned back to it's original CSS state... So that makes no sense.

Are you seeing this behavior @simurai?

Style scrollbars on Windows?

Loading the app on Windows 10 shows a scrollbar on the left hand side:

Maybe it should be styled explicitly or at least make the default height high enough to not show it?

/cc @simurai

Design Refinement

Here some (random) styling improvements. Feel free to add more.

Add more contrast to the colors #23
Fix scrolling after navigating #31
Add link to repo/source #39
App icon #49
Use <button> for the .content h2 so keyboard can be used to open?
Add some padding at the bottom if there is no pro tip.

Minimal demo of demo...

I've got things wired up for a minimal demo of how it would be with one section, the dialog, section fleshed out. All of the colors/design stuff is just placeholder.

It would be good to maybe have a 👖 with @simurai and @benogle this week if possible to take a look at it?

main page (all of the categories aren't built out yet, just dialogs one)

dialogs page with collapsed sections

expanded section

Ideas

A rough list of ideas I had while going through the app:

Adapt more demos

https://github.com/hokein/electron-sample-apps has lots of goodies:

~~camera~~
~~client-certificate~~
~~cookies~~
~~crash-report~~
desktop-capture
~~file-explorer~~
frameless-window
~~helloworld~~
~~helloworld-sharedobj~~
menus
~~mini-code-edit~~
~~mp3-encoder~~
~~notifications~~
~~pepper-flash-plugin~~
~~power-save-blocker~~
printing
spellcheck
tray
~~webgl~~
webview

Some of these are already covered in our demo. Others not. Thoughts?

Update dependencies that use a deprecated version of graceful-fs

❯ npm i              
npm WARN deprecated [email protected]: graceful-fs version 3 and before will fail on newer node releases. Please update to graceful-fs@^4.0.0 as soon as possible.
npm WARN deprecated [email protected]: graceful-fs version 3 and before will fail on newer node releases. Please update to graceful-fs@^4.0.0 as soon as possible.

The Offenders

This is kind of a wild goose chase, as the dependency is pretty deep in the tree in some spots. The two top-level offenders are mocha and eletron-packager.

❯ npm ls graceful-fs@'<4'
[email protected] /Users/zeke/atom/electron-api-demos
├─┬ [email protected]
│ └─┬ [email protected]
│   └─┬ [email protected]
│     └─┬ [email protected]
│       └── [email protected] 
└─┬ [email protected]
  └─┬ [email protected]
    └── [email protected]

Outstanding PRs

Rename Printing Category to Media

Because now it has more sections ✨ Discussed in #139 and just opening an issue here to keep it on my radar.

Consistent Consts...and Others

We started using the const, let and string templates in places but we don't use them everywhere. It makes sense to be consistent all over, right? Just wanted to check because I can go through and do a sweet to make this so 👍