tysenmoore-xse / ngelectron

The ngElectron service for AngularJS making it easier to interface with Electron.

New Release: electangular.js

Check out the latest release that supersedes ngElectron

Learn more about electangular.js

---

ngElectron - AngularJS Electron Service

An AngularJS service module making it easier to interface with Electron.

Install

Start by downloading the ngElectron bundle: Download Here

Unzip the archive and move the ng-electron.js and ng-bridge.js to an accessable path.

Setup

Add the ng-electron.js to your main Electron app index.html page.

<!-- Electron : index.html -->
<script type="text/javascript" src="./client/lib/ng-electron/ng-electron.js"></script>

Inject the ngElectron module in the main app.js

// AngularJS : app.js
var app = angular.module('app', ['ngElectron']);

Add the module to controllers by using the electron namespace.

// AngularJS : controllers.js
app.controller('myController', ['electron', function(electron) {
  electron.dialog.showErrorBox('Oppps!','Looks like I messed something up...');
}]);

An Electron system menu created in AngularJS...

// AngularJS : controllers.js
app.controller('myController', ['electron', function(electron) {

  //Get a reference to the Electron Menu class.
  var Menu = electron.menu

  var menu_tpl = [
    {
      label: 'Do Something'
      click: null
    }
  ]
  var menu = Menu.buildFromTemplate( menu_tpl );
  Menu.setApplicationMenu( menu );

}]);

Communicating with Electron

Using the ng-bridge.js in Electron, AngularJS can send and listen for messages from the main host process.

The main process/Chrome is generally referred to as the "host" in the ngElectron documentation.

When ngElectron starts, AngularJS will listen for incoming messages from the host and broadcast them throughout the AngularJS eco-system. AngularJS code can listen for host messages through the $rootScope emitters and "electron-host" event type.

app.run(['$rootScope', function($rootScope) {
  //listen for host messages
  $rootScope.$on('electron-host', function(evt, data) {
    console.log( data + " from HOST" );
  });
}]);

Sending a message to the host

To send a message to the host simply use the send method in the electron namespace:

app.controller('myController', ['electron', function(electron) {
  electron.send("Hello from the client.");
}]);

Important: Electron needs the ng-bridge.js module initiated first, before communicating with AngularJS. See the next section for setup details.

---

Angular Bridge for Electron

The included ng-bridge.js Electron module pairs with ngElectron to create simple bi-directional communication between AngularJS and Electron using the built in ipc Electron functionality.

Usage

Require the ng-bridge.js module where you plan on using it:

// Electron : index.js
var angular = require('./client/lib/ng-electron/ng-bridge');

Listen for messages from AngularJS in Electron:

// Electron : index.js
app.on('ready', function() {
  angular.listen( function( msg ) {
    console.log( msg );
  });
});

Send a message to the AngularJS client:

// Electron : index,js

// Specify a BrowserWindow
angular.send("Hello from the host.", mainWindow);

// If no BrowserWindow is specified, ng-bridge will attempt to capture the window that is focused in the application.
angular.send("Hello from the host.");

Note If a window is neither specified, or found, the message will not send to the client.

---

Calling Electron from AngularJS

One very useful feature of ngElectron is the direct access to Electron, and included Node packages.

To quickly access the Electron dialog lib from the host process, and open a prompt from AngularJS:

mod.controller('myController',['electron', function(electron) {
  electron.dialog.showErrorBox('Opps', 'I did it again.');
}]);

The following direct refs can be used in AngularJS controllers through the electron namespace:

Custom

• send
• db

DiskDB is supported if the package is installed:

npm install diskdb --save

ShellJS is also supported if the package is installed:

npm install shelljs --save

Note: If you are using the Amy App Stack, diskdb is already installed and configured.

Electron

• app
• browserWindow
• clipboard
• dialog
• menu
• menuItem
• nativeImage
• powerMonitor
• protocol
• require
• screen
• shell
• tray

Using an Electron module in AngularJS

// AngularJS
angular.module('app', ['ngElectron'])

.controller('myController', ['electron', function(electron) {
  //Some methods require a class ref first
  //which you can do through the electron namespace.
  var BrowserWindow = electron.browserWindow;
  var win = new BrowserWindow( args );
}])

.controller('dockController', ['electron', function(electron) {
  //And others can be called directly
  electron.app.dock.bounce();
}])

Node

• buffer
• childProcess
• crypto
• dns
• emitter
• fs
• http
• https
• net
• os
• path
• querystring
• url
• zlib

Using a Node module in AngularJS

// AngularJS
angular.module('app', ['ngElectron'])

.controller('dnsController', ['$scope','electron',
function($scope, electron) {
  electron.dns.resolve("http://google.com", function(err, addrs) {
    $scope.address = addrs[0];
    $scope.$apply();
  });
}]);

Integrate ngElectron into an existing project

If you have an existing AngularJS Electron based project, you can integrate ngElectron pretty easily. After following the steps below, make sure to read up on the ngElectron module in the documentation above.

With the terminal, navigate to your AngularJS 'client' files and run:

bower install develephant/ng-electron --save

Now link the js files to the index.html of your Electron project:

<!-- Add the ng-electron module for AngularJS -->
<script type="text/javascript" src="client/lib/ng-electron/ng-electron.js"></script>

Inject the ngElectron module dependency into your AngularJS project:

//Main app initialization
var app = angular.module('myApp', ['ngElectron']);

//A controller
app.controller('myController', ['electron',
function(electron) {
  electron.send("Hello Host! From Client.");
}])

Make sure to use DI for ngElectron in any AngularJS modules you create that need access to Electron:

var mod = angular.module('myModule', ['ngElectron']);

---

Contributors

👷 MarkRabey 👷 dgoradia 👷 nicam 👷 ojwebtech

---

(c)2015-16 C. Byerley @develephant 🐘 All rights reserved by the originals owners, maintainers, and creators.