|
| 1 | +# Quick start |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +Generally, atom-shell enables you to create desktop applications with pure |
| 6 | +JavaScript by providing a runtime with rich native APIs, you could see it as |
| 7 | +an variant of node.js runtime that focused on desktop applications instead of |
| 8 | +web server. |
| 9 | + |
| 10 | +But it doesn't mean atom-shell is a JavaScript binding to GUI libraries, instead |
| 11 | +atom-shell uses web pages as GUI, so you could also see it as a minimal Chromium |
| 12 | +browser, controlled by JavaScript. |
| 13 | + |
| 14 | +### The browser side |
| 15 | + |
| 16 | +If you had experience with node.js web applications, you would notice that there |
| 17 | +are types of JavaScript scripts: the server side scripts and the client side |
| 18 | +scripts. The server side JavaScript, is the scrips that run on the node.js |
| 19 | +runtime, and the client side JavaScript, is the ones that run on user's browser. |
| 20 | + |
| 21 | +In atom-shell we have similar concepts, since atom-shell displays GUI by showing |
| 22 | +web pages, we would have scripts that run in the web page, and also have scripts |
| 23 | +ran by the atom-shell runtime, which created those web pages. Like node.js, we |
| 24 | +call the former ones client client scripts, and the latter one browser side |
| 25 | +scripts. |
| 26 | + |
| 27 | +In traditional node.js applications, communication between server side and |
| 28 | +client side are usually done by web sockets. In atom-shell, we have provided |
| 29 | +the [ipc](../api/renderer/ipc-renderer.md) module for browser side to client |
| 30 | +communication, and the [remote](../api/renderer/remote.md) module for easy RPC |
| 31 | +support. |
| 32 | + |
| 33 | +### Web page and node.js |
| 34 | + |
| 35 | +Normal web pages are designed to not touch outside world, which makes them not |
| 36 | +suitable for interacting with native systems, atom-shell provides node.js APIs |
| 37 | +in web pages so you could access native resources in web pages, just like |
| 38 | +[node-webkit](https://github.com/rogerwang/node-webkit). |
| 39 | + |
| 40 | +But unlike node-webkit, you could not do native GUI related operations in web |
| 41 | +pages, instead you need to do them on the browser side by sending messages or |
| 42 | +use the easy [remote](../api/renderer/remote.md) module. |
| 43 | + |
| 44 | + |
| 45 | +## Write your first atom-shell app |
| 46 | + |
| 47 | +Generally, an atom-shell app would be like this: |
| 48 | + |
| 49 | +```text |
| 50 | +app/ |
| 51 | +├── package.json |
| 52 | +├── main.js |
| 53 | +└── index.html |
| 54 | +``` |
| 55 | + |
| 56 | +The format of `package.json` is exactly the same with node's modules, and the |
| 57 | +script specified by the `main` field is the startup script of your app, which |
| 58 | +will run under the browser side. An example of your `package.json` is like |
| 59 | +this: |
| 60 | + |
| 61 | +```json |
| 62 | +{ |
| 63 | + "name" : "your-app", |
| 64 | + "version" : "0.1.0", |
| 65 | + "main" : "main.js" |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +The `main.js` should create windows and handle system events, and an typical |
| 70 | +example is: |
| 71 | + |
| 72 | +```javascript |
| 73 | +var app = require('app'); // Module to control application life. |
| 74 | +var BrowserWindow = require('browser-window'); // Module to create native browser window. |
| 75 | + |
| 76 | +// Report crashes to our server. |
| 77 | +require('crash-reporter').start(); |
| 78 | + |
| 79 | +// Keep a global reference of the window object, if you don't, the window will |
| 80 | +// be closed automatically when the javascript object is GCed. |
| 81 | +var mainWindow = null; |
| 82 | + |
| 83 | +// Quit when all windows are closed. |
| 84 | +app.on('window-all-closed', function() { |
| 85 | + if (process.platform != 'darwin') |
| 86 | + app.quit(); |
| 87 | +}); |
| 88 | + |
| 89 | +// This method will be called when atom-shell has done everything |
| 90 | +// initialization and ready for creating browser windows. |
| 91 | +app.on('ready', function() { |
| 92 | + // Create the browser window. |
| 93 | + mainWindow = new BrowserWindow({width: 800, height: 600}); |
| 94 | + |
| 95 | + // and load the index.html of the app. |
| 96 | + mainWindow.loadUrl('file://' + __dirname + '/index.html'); |
| 97 | + |
| 98 | + // Emitted when the window is closed. |
| 99 | + mainWindow.on('closed', function() { |
| 100 | + // Dereference the window object, usually you would store windows |
| 101 | + // in an array if your app supports multi windows, this is the time |
| 102 | + // when you should delete the corresponding element. |
| 103 | + mainWindow = null; |
| 104 | + }); |
| 105 | +}); |
| 106 | +``` |
| 107 | + |
| 108 | +Finally the `index.html` is the web page you want to show: |
| 109 | + |
| 110 | +```html |
| 111 | +<!DOCTYPE html> |
| 112 | +<html> |
| 113 | + <head> |
| 114 | + <title>Hello World!</title> |
| 115 | + </head> |
| 116 | + <body> |
| 117 | + <h1>Hello World!</h1> |
| 118 | + We are using node.js <script>document.write(process.version)</script> |
| 119 | + and atom-shell <script>document.write(process.versions['atom-shell'])</script>. |
| 120 | + </body> |
| 121 | +</html> |
| 122 | +``` |
| 123 | + |
| 124 | +## Run your app |
| 125 | + |
| 126 | +After done writing your app, you could create a distribution of your app by |
| 127 | +following the [Application distribution](./application-distribution.md) guide |
| 128 | +and then execute the packaged app, or you can just use the downloaded atom-shell |
| 129 | +binary to execute your app directly. |
| 130 | + |
| 131 | +On Window: |
| 132 | + |
| 133 | +```cmd |
| 134 | +$ .\atom-shell\atom.exe app |
| 135 | +``` |
| 136 | + |
| 137 | +On Linux: |
| 138 | + |
| 139 | +```bash |
| 140 | +$ ./atom-shell/atom app |
| 141 | +``` |
| 142 | + |
| 143 | +On Mac OS X: |
| 144 | + |
| 145 | +```bash |
| 146 | +$ ./Atom.app/Contents/MacOS/Atom app |
| 147 | +``` |
0 commit comments