Building dapps on Ethereum - part 3: user interface

What's beautiful with Ethereum is that it's a new kind of Internet — an ecosystem of decentralised computational resources and applications. But at the same time Ethereum work with tools and protocols of the old Internet where it makes sense. In this blog post we'll go through how to write an user interface (UI) in HTML5 and Javascript (JS) for our decentralised application that we started building in part 2 of this series.

Before we begin

If you haven't already, I would recommend you to read the previous posts in this series:

• Part 1: overview
• Part 2: smart contracts

Because we can use regular HTML5 and Javascript to build our user interface it's actually very straight forward. What consumed the most time for me was setting up my front-end development toolkit, not actually connecting the blockchain wires for the dapp!

Throughout this blog post series we will use sample code from the Iron Doers project which is a quite simple concept briefly described in a practical example of using blockchains and the project's whitepaper.

Web 3.0

As already mentioned, the UI is a seemingly regular HTML5 and JS app. But the key difference is the connection to the third web – the decentralised web! There are two vital components to this (1) the web3.js library and (2) a browser that knows how to use the connection and can associate an account (wallet) key-pair with the browser session.

Front-end basics

Oh goodness, front-end tooling is moving fast!There are numerous nice UI frameworks out there like React, Angular or Ember that often are used with a layout systems like Bootstrap and pre-processed with Less or Sass. Further, we have automation, packaging and task runners like [npm][npm], Grunt, Gulp, Browserify and Webpack (or all of them together). Since the focus of this series is the creation of a decentralised application we will only cover the bare minimum for creating a UI. We'll keep it short and simple with just npm, webpack and straight-up Bootstrap (no pre-processing).

We'll start by defining our UI dependencies in package.json (in the repo root). The main packages are (1) web3 used for connecting to the decentralised web (2) truffle-contract to create JS abstractions of our contract binaries on the blockchain (3) webpack for bundling all assets into a single app and (4) bootstrap for making things look pretty.

{
  "name": "irondoers",
  "version": "0.0.1",
  "description": "Decentralised application made to incentivise doers in a democratic autonomous organisation.",
  "repository": "https://github.com/dickolsson/irondoers",
  "scripts": {
    "build": "webpack",
    "dev": "webpack-dev-server"
  },
  "author": "Dick Olsson",
  "license": "GPL-3.0",
  "devDependencies": {
    "web3": "~0.18",
    "json-loader": "~0.5",
    "truffle-contract": "~1",
    "webpack": "~2",
    "webpack-dev-server": "~2",
    "bootstrap": "~3"
  }
}

Before we can bundle our dependencies into a single JS application we must define webpack.config.js (in the repo root). The three main things going on here is (1) the app will be output to ./www/bundle.js (2) jQuery will be provided to any library that needs it, primarily Bootstrap in our case and (3) our development server will use ./www as the document root.

var webpack = require("webpack");
var path = require("path");
const www = path.resolve(__dirname, "www");

module.exports = {
  entry: "./src/app.js",
  output: {
    filename: "bundle.js",
    path: www
  },
  module: {
    rules: [],
    loaders: [
      {
        test: /\.json$/,
        use: "json-loader"
      }
    ]
  },
  plugins: [
    new webpack.ProvidePlugin({
      $: "jquery",
      jQuery: "jquery"
    })
  ],
  devServer: {
    contentBase: www
  }
}

The HTML5 portion of our dapp is placed at ./www/index.html and the full source code of this file can be found in the example repo. It's a basic Bootstrap structure and won't need much explanation.

The dapp

The JS portion of our dapp is placed at ./src/dapp.js and the full source code can be found in the example repo. Below I'll explain fragments of the more important parts.

At the bottom on the dapp source code we (1) prepare the connection to the provided blockchain (with fallback on our local blockchain) (2) check that the user have connected an account with the browser and (3) connecting our contract abstraction to the blockchain as well.

For all this to work, you need to use a browser that can browse the decentralised web like Mist or the Status mobile app.

The functions setDoerCount and addDoer are the UI to the equivalent call and transaction functions in our smart contract that we developed in part 2 of this series. As you can see the interaction with the contract's JS abstraction is identical to those in the Mocha tests, so we can already be sure that these will work!

var Web3 = require("web3");
var contract = require("truffle-contract");
var IronDoers = contract(require("../build/contracts/IronDoers.json"));
require("bootstrap");
var account;

window.Dapp = {
  start: function() {
    this.setDoerCount();
  },

  setAlert: function(message, type) {
    type = type || "info";
    var element = document.getElementById("alerts");
    element.innerHTML = "
" + message + "";
  },

  throwError: function(message, err) {
    err = err || message;
    this.setAlert("Error! " + message, "danger");
    throw err;
  },

  setDoerCount: function() {
    IronDoers.deployed().then(function (instance) {
      return instance.getDoerCount.call();
    }).then(function (value) {
      var element = document.getElementById("doer-count");
      element.innerHTML = value.valueOf();
    });
  },

  addDoer: function() {
    var self = this;
    var address = document.getElementById("doer-address").value;
    IronDoers.deployed().then(function(instance) {
      self.setAlert("Adding doer...");
      return instance.addDoer(address, {from: account});
    }).then(function() {
      self.setDoerCount();
      self.setAlert("Doer was added!", "success");
    });
  }
};

window.addEventListener("load", function() {
  if (typeof web3 !== "undefined") {
    window.web3 = new Web3(web3.currentProvider);
  } else {
    window.web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8545"));
  }
  try {
    var accounts = web3.eth.accounts;
  } catch(err) {
    Dapp.throwError("Use a browser that can browse the decentralized web!", err);
  }
  if (accounts.length == 0) {
    Dapp.throwError("Connect an account!");
  }
  account = accounts[0];
  IronDoers.setProvider(web3.currentProvider);
  IronPromise.setProvider(web3.currentProvider);
  Dapp.start();
});

Installing and testing locally

1. Install the Mist browser.
2. Start a blockchain with geth according to the bonus instructions at the bottom of the part 2 post (don't forget to start a miner).
3. Compile and migrate the contracts to your new blockchain (again see part 2)

Now we need to install all dependencies and start a local web server to host our dapp. The local web server is provided by the webpack-dev-server package that we defined in package.json earlier.

$ npm install
$ npm run dev

In a new terminal window, launch the Mist browser with a special parameter to connect to the local blockchain:

$ /Applications/Mist.app/Contents/MacOS/Mist --rpc http://127.0.0.1:8545

And now you can start interacting with your new decentralised application!