Forem: Newton Munene

Creating a Whatsapp chatbot using Node JS, Dialogflow and Twilio

Newton Munene — Fri, 03 Jan 2020 09:28:45 +0000

I'm going to walk you through creating a WhatsApp chatbot using Dialogflow. I initially wanted to do this in several blog posts but I'm going to cover it all in one. Brace yourself it might be a bit long.

Prerequisites

Twilio account
Dialogflow account
Node Js
Javascript knowledge

Getting Started

Install the latest stable version of Node Js if you don't have it.

Twilio

Visit twilio and sign up for a new account if you do not have one. You'll be given some credits to get you started. After they are over you'll need to pay to get more so use them wisely.

On your dashboard take note of your Account SID and Auth Token.
Head over to https://www.twilio.com/console/sms/whatsapp/learn and follow the instructions to connect your Whatsapp account to your sandbox. This is necessary for the sandbox environment. This is all you need for now, we'll come back to this later.

Dialogflow

According to their website ,

Dialogflow is an end-to-end, build-once deploy-everywhere development suite for creating conversational interfaces for websites, mobile applications, popular messaging platforms, and IoT devices. You can use it to build interfaces (such as chatbots and conversational IVR) that enable natural and rich interactions between your users and your business. Dialogflow Enterprise Edition users have access to Google Cloud Support and a service level agreement (SLA) for production deployments.

We will be using Dialogflow to power our chatbot. Head over to Dialogflow Console and create a new agent. I will not dive into the specifics of creating and training agents, handling entities, intents and more. That is beyond the scope of this tutorial. You can find multiple resources on this online.

After creating your agent, click on the Small Talk tab on the left and enable it. This allows our bot to respond to small talk and common phrases. You can customize the responses on the same tab. You can do this for a more personalized experience. On the right side of your Dialogflow console, there's an input field where you can test out your bot.

When you've tested out your bot and are satisfied you can now follow the steps below to set up authentication for accessing your chatbot via an API.

On your Dialogflow console, open settings by clicking on the gear icon next to our project name.
Take note of the Project Id that is on the General tab of the settings page under Google Project section. We'll be using that later.
Follow the link next to Service Account.

Create a new service account, give it an appropriate name.

Set Dialogflow role to Dialogflow API Admin

Create a new key and choose JSON.

Rename the downloaded JSON file to credentials.json. This is just so we can reference it easily. We will come back to this file later.

Backend (Node JS)

I will be using typescript in this project. You shouldn't feel intimidated even if you haven't used it before. You can check out this guide on how to get started with typescript and express.

Open your terminal and create a new project.

mkdir wa-chatbot && cd wa-chatbot

Initialize a new node js project inside the folder we just created and changed directory into

npm init -y

Install the following dev dependencies

nodemon
typescript
ts-node
ts-lint

npm i -D nodemon typescript ts-node ts-lint

Install the following dependencies

express
dotenv
twilio
dialogflow
@overnightjs/core
@overnightjs/logger
body-parser
cors

We're using Overnight to stay closer to the MVC pattern and utilize Object Oriented style of programming. Read more about Overnight here .

npm i -S express dotenv twilio dialogflow @overnightjs/core @overnightjs/logger body-parser cors

We also need to install types for these modules

npm i -D @types/node @types/express @types/twilio @types/dialogflow @types/body-parser @types/cors

Next, we'll create a tsconfig.json file. In the root of your project make a new file.

touch tsconfig.json

Copy and paste the following content inside the new file

{
  "compilerOptions": {
    "module": "commonjs",
    "strict": true,
    "baseUrl": "./",
    "outDir": "build",
    "removeComments": true,
    "experimentalDecorators": true,
    "target": "es6",
    "emitDecoratorMetadata": true,
    "moduleResolution": "node",
    "importHelpers": true,
    "types": ["node"],
    "typeRoots": ["node_modules/@types"]
  },
  "include": ["./src/**/*.ts"],
  "exclude": ["./src/public/"]
}

I will not go into the specifics for now but you can read typescript documentation for more information.
Next, create a tslint.json file at the root of your project and paste the following content inside.

{
  "defaultSeverity": "warning",
  "extends": ["tslint:recommended"],
  "jsRules": {},
  "rules": {
    "trailing-comma": [false],
    "no-bitwise": false,
    "jsdoc-format": true,
    "deprecation": true,
    "interface-name": true,
    "no-duplicate-imports": true,
    "no-redundant-jsdoc": true,
    "no-use-before-declare": true,
    "variable-name": false,
    "object-literal-sort-keys": false,
    "member-ordering": true,
    "await-promise": true,
    "curly": true,
    "no-async-without-await": true,
    "no-duplicate-variable": true,
    "no-invalid-template-strings": true,
    "no-misused-new": true,
    "no-invalid-this": true,
    "prefer-const": true
  },
  "rulesDirectory": []
}

Let's set up our backend structure.
Open your terminal and run the following commands inside the root of your project.

mkdir src && touch src/AppServer.ts && touch src/start.ts

AppServer.ts is where we will set up our express app.
Paste the following inside src/AppServer.ts

import * as bodyParser from "body-parser";
import * as controllers from "./controllers";
import { Server } from "@overnightjs/core";
import { Logger } from "@overnightjs/logger";
import * as cors from "cors";
export class AppServer extends Server {
  private readonly SERVER_STARTED = "Server started on port: ";

  constructor() {
    super(true);
    this.app.use(bodyParser.json());
    this.app.use(bodyParser.urlencoded({ extended: true }));
    this.app.use(cors());
    this.setupControllers();
  }

  private setupControllers(): void {
    const ctlrInstances = [];
    for (const name in controllers) {
      if (controllers.hasOwnProperty(name)) {
        const controller = (controllers as any)[name];
        ctlrInstances.push(new controller());
      }
    }
    super.addControllers(ctlrInstances);
  }

  public start(port: number): void {
    this.app.get("*", (req, res) => {
      res.send(this.SERVER_STARTED + port);
    });
    this.app.listen(port, () => {
      Logger.Imp(this.SERVER_STARTED + port);
    });
  }
}

In this file, we set up our AppServer class which extends the Server class from Overnight. In the constructor we initialise the Server class passing true as a parameter. We then head on to configure some middlewares for our app. We might be receiving JSON data in our requests so we use body-parser to ensure it's handled properly.

We then set up our controllers which we will create in a short while. After this, we define the start method which will start up the app on the port passed to it as a parameter

Paste this into src/start.ts. This is the starting point for our application.

import { config } from "dotenv";
config();
import { AppServer } from "./AppServer";

const appServer = new AppServer();
appServer.start(3000);

At the top, we import config from dotenv and call it. We use this to configure our environment variables and load them into process.env. We also initiate a new instance of the server and call the start method passing in a port to use.

At this point, we need to set up our controllers. Create a folder inside src and call it controllers. Inside src/controllers create two files: BotController.ts and index.ts

Inside BotController.ts paste the following code

import { Request, Response } from "express";
import { Controller, Post } from "@overnightjs/core";
import { Logger } from "@overnightjs/logger";

@Controller("api/bot")
export class BotController {

}

You'll notice some weird syntax just before our controller class. That's a decorator. We use it to tell the compiler that our class is a controller. We also pass an argument which is our URL path. With this, we can now make restful requests to [SERVER]:[PORT]/api/bot.

We don't have any routes defined yet. For Twilio, we will only need a POST route. Inside the BotController class add the following code.

@Post()
  private postMessage(request: Request, response: Response) {
    Logger.Info("A post request has been received");
    return response.status(200).json({
      message: "A post request has been received"
    });
  }

You'll notice another decorator which tells our compiler that the method handles POST requests.

In src/controllers/index.ts add the following code. This exports our controllers so that it will be easy to export any future controllers.

export * from "./BotController";

The fun stuff

It's time to get to the fun stuff. Let's set up our app to communicate with Twilio and Dialogflow.
Create a folder called utils under src. Inside utils create two files: dialogflow.ts and twilio.ts

Inside Dialogflow.ts:

// dialogflow.ts

const dialogflow = require("dialogflow");
const credentials = require("../../credentials.json");

const sessionClient = new dialogflow.SessionsClient({
  credentials: credentials
});
const projectId: string = process.env.DIALOGFLOW_PROJECT_ID!;

export const runQuery = (query: string, number: string) => {
  return new Promise(async (resolve, reject) => {
    try {
      // A unique identifier for the given session
      //const sessionId = uuid.v4();
      const sessionId = number;
      // Create a new session

      const sessionPath = sessionClient.sessionPath(projectId, sessionId);

      // The text query request.
      const request = {
        session: sessionPath,
        queryInput: {
          text: {
            // The query to send to the dialogflow agent
            text: query,
            // The language used by the client (en-US)
            languageCode: "en-US"
          }
        }
      };

      // Send request and log result
      const responses = await sessionClient.detectIntent(request);

      const result = responses[0].queryResult;

      resolve(result);
    } catch (error) {
      reject(error);
    }
  });
};

Here we're importing Dialogflow and also the credentials.json file we downloaded when setting up our chatbot on Dialogflow. Remember that file? Move it to your project's root folder. We're the setting up a new SessionsClient using the credentials file. In our runQuery function we're taking in a query to send to Dialogflow and also the user's Whatsapp number which we will use to set up a Dialogflow session unique to that user. We then send the query to Dialogflow and return the response.

In twilio.ts add the following code :

import { Twilio } from "twilio";
const accountSid = process.env.TWILIO_ACCOUNT_SID!;
const authToken = process.env.TWILIO_AUTH_TOKEN!;

const client = new Twilio(accountSid, authToken);

export const sendMessage = (to: string, from: string, body: string) => {
  return new Promise((resolve, reject) => {
    client.messages
      .create({
        to,
        from,
        body
      })
      .then(message => {
        resolve(message.sid);
      })
      .catch(error => {
        reject(error);
      });
  });
};

Here we create a new Twilio client and instantiate using our Twilio Account SID and Auth Token. We then call the client.messages.create function which takes in the number of the user, the number sending the message(in this case, the Twilio sandbox number) and also a body. We then return the message Id.

You've probably noticed we've used a few environment variables that we haven't defined yet. In the root of your project create a .env file. Inside paste the following code and make sure to replace placeholders with appropriate values. I asked you to take note of the values required at some point in this tutorial.

TWILIO_ACCOUNT_SID=PLACEHOLDER
TWILIO_AUTH_TOKEN=PLACEHOLDER
DIALOGFLOW_PROJECT_ID=PLACEHOLDER

Go back to BotController.ts and replace the postMessage method with the following code.

@Post()
  private postMessage(request: Request, response: Response) {
    // Here we get the message body, the number to which we're sending the message, and the number sending the message.
    const { Body, To, From } = request.body;

    // Here we're sending the received message to Dialogflow so that it can be identified against an Intent.
    runQuery(Body, From)
      .then((result: any) => {
        // We send the fulfilment text received back to our user via Twilio
        sendMessage(From, To, result.fulfillmentText)
          .then(res => {
            console.log(res);
          })
          .catch(error => {
            console.error("error is ", error);
            Logger.Err(error);
          });
      })
      .catch(error => {
        console.error("error is ", error);
        Logger.Err(error);
      });
    return response.status(200).send("SUCCESS");
  }

Twilio hits this method when it receives a message from Whatsapp. We extract the message body, the sender, and the recipient(in this case, Twilio sandbox number). We then send the received body to Dialogflow and get a fulfilment text. We use the Twilio client we set up earlier to send back the fulfilment text to the user.

Now there's only one more thing left to do. Open up your package.json and replace the scripts with the following

"scripts": {
    "tsc": "tsc",
    "prestart": "npm run build",
    "dev": "ts-node src/start.ts",
    "dev:watch": "nodemon",
    "build": "rm -rf ./build/ && tsc",
    "start": "node build/start.js"
  },

The full file looks this

{
  "name": "wa-chatbot",
  "version": "1.0.0",
  "description": "",
  "main": "build/start",
  "scripts": {
    "tsc": "tsc",
    "prestart": "npm run build",
    "dev": "ts-node src/start.ts",
    "dev:watch": "nodemon",
    "build": "rm -rf ./build/ && tsc",
    "start": "node build/start.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@types/body-parser": "^1.17.1",
    "@types/cors": "^2.8.6",
    "@types/dialogflow": "^4.0.4",
    "@types/express": "^4.17.2",
    "@types/node": "^13.1.2",
    "@types/twilio": "^2.11.0",
    "nodemon": "^2.0.2",
    "ts-lint": "^4.5.1",
    "ts-node": "^8.5.4",
    "typescript": "^3.7.4"
  },
  "dependencies": {
    "@overnightjs/core": "^1.6.11",
    "@overnightjs/logger": "^1.1.9",
    "body-parser": "^1.19.0",
    "cors": "^2.8.5",
    "dialogflow": "^1.0.0",
    "dotenv": "^8.2.0",
    "express": "^4.17.1",
    "twilio": "^3.39.1"
  }
}

You can run npm install again in case I missed any dependencies. We also need to set up nodemon. Create a nodemon.json in your project's root folder and paste the following inside.

{
  "watch": ["src"],
  "ext": "ts",
  "ignore": ["src/public"],
  "exec": "NODE_ENV=development ts-node src/start.ts"
}

You can now run npm run dev:watch and see if your project runs successfully. Next, we need to expose our local server. Ngrok is one of the best open-source solutions but you can use whatever you prefer.

Copy your exposed server URL and open Twilio Whatsapp Sandbox. Replace the URL in WHEN A MESSAGE COMES IN with your exposed URL. Don't forget to add the path to our bot controller. i.e. /api/bot

Save the new changes and you can now send a message to the Twilio Sandbox Number and you'll see the response.

Here's some homework for you. Create a new controller to handle POST requests and pass the URL to the STATUS CALLBACK URL input on the Twilio Whatsapp Sandbox. Be creative and be notified when a user reads your message and when it's delivered.

The full source code can be found here https://github.com/newtonmunene99/wa-chatbot

Essential dart list/array methods.

Newton Munene — Thu, 01 Aug 2019 08:26:12 +0000

I have been playing around with Flutter for a few months now and I'm starting to get a good grip on the concepts of dart, the language that drives flutter. I do, however, often find myself on google looking up array methods. I thought I'd cover them in this post for my own reference and also for anyone who faces the same predicament. Coming from a web/js background, the methods are very similar to Javascript array methods. Let's dive in.

Prerequisites

There really isn't any but let's mention something anyway.

Flutter / Dart
OOP Knowledge

You can follow along using DartPad, a playground for dart. You can also refer to the official docs.

Getting started

Open up DartPad and we'll get started.

Paste the following code inside dartpad and run it.

void main() {
  List<String> fruits = ['mangoes','bananas','pears','oranges'];
  print(fruits);
}

You will immediately notice the type annotation when declaring our fruits variable. This improves readability and IntelliSense when using a code editor like Visual Studio Code. It is also type-safe, which means you cannot assign anything other than strings. The above code can also be written as

void main() {
  var fruits = ['mangoes','bananas','pears','oranges'];
  print(fruits);
}

What if we wanted to add items of different types? Well, the code immediately above will work. But you can also change List<String> to List<dynamic>. Now you can add integers, strings, booleans even other lists.

const and final

Can you guess what happens when we mark our list as either final or const? Let's find out.
Change your code to this

void main() {
  final List<String> fruits = ['mangoes','bananas','pears','oranges'];
  fruits.add('apples');
  print(fruits);
}

Run it. You'll notice that apples have been added to our list. Marking as final means we cannot reassign our variable. We can, however, mutate our list. Now let's try something else.

void main() {
  final List<String> fruits = ['mangoes','bananas','pears','oranges'];
  fruits = [...fruits,'apples'];
  print(fruits);
}

You will immediately get an error.
How can we mark our list as immutable? Yes, you already guessed it. Using the const keyword. We can do this in two ways.

void main() {
  final List<String> fruits = const ['mangoes','bananas','pears','oranges'];
  //fruits.add('apples');
  print(fruits);
}

void main() {
  const List<String> fruits = ['mangoes','bananas','pears','oranges'];
  //fruits.add('apples');
  print(fruits);
}

Uncomment fruits.add('apples'); and try running both. The two implementations are not entirely similar. I will cover deeply when I also have a better understanding.

There's just one more thing to cover before we get down to the main event.

Creating lists

We've already seen one way of creating lists. That is what we have been using from the start of this article. We will cover a few more methods which might come in handy.

1.List(int length)

void main() {
  var list = List(5);
  print(list); //output - [null, null, null, null, null]
}

This creates a list of length 5 with null as its items/values.

2.List.filled(int length,dynamic fill,{bool growable})

void main() {
  var list = List.filled(5, "hello");
  print(list); // output - [hello, hello, hello, hello, hello]
}

It takes in a length and whatever you want the list to fill at each index. You can also specify growable, which accepts a boolean, as an optional named parameter.

void main() {
  var list = List.filled(5, "hello",growable:true);
  list.add('hello');
  print(list); // output - [hello, hello, hello, hello, hello, hello]
}

growable determines if we can add/remove items.

3.List.generate(int length, dynamic generator(int index),{bool growable})

void main() {
  var list = List.generate(5,(index) =>index +2,growable:true);
  print(list); //output - [2, 3, 4, 5, 6]
}

I believe you have already figured out what's going on with the generator. It takes in the index and returns whatever you want to fill at that index.

4.List.from(Iterable list,{bool growable})

void main() {
  var list = List.generate(5,(index) =>"hello $index",growable:true);
  print(list); //output - [hello 0, hello 1, hello 2, hello 3, hello 4]
  var list2 = List.from(list,growable:false);
  print(list2); //output - [hello 0, hello 1, hello 2, hello 3, hello 4]
}

This one creates a new list from another list or iterable.

There are a few more ways but these are the most common.

Now we can get started with the methods.

List methods and properties

1.add

We have already seen this method several times already. It is used to add items to a growable list.

void main() {
  var fruits = ['mangoes','bananas'];
  fruits.add('apples');
  print(fruits); //output - [mangoes, bananas, apples]
}

2.remove

This method removes an object/item from a growable list. Make sure your values are unique else it removes only the first match.

void main() {
  var fruits = ['mangoes','bananas','apples'];
  fruits.remove('mangoes');
  print(fruits); //output - [bananas, apples]
}

3.removeAt

This method removes the item at the specified index

void main() {
  var fruits = ['mangoes','bananas','apples'];
  fruits.removeAt(1);
  print(fruits); //output - [mangoes, apples]
}

4.addAll

Adds all items of the specified Iterable.

void main() {
  var fruits = ['mangoes','bananas','apples'];
  var morefruits = ['peaches','plums'];
  fruits.addAll(morefruits);
  print(fruits); //output - [mangoes, bananas, apples, peaches, plums]
}

5.asMap

Returns a map representation of the List with the indices as keys and items of the array as the values.

void main() {
  var fruits = ['mangoes','bananas','apples'];

  print(fruits.asMap()); //output - {0: mangoes, 1: bananas, 2: apples}
}

6.insert and insertAll

These are similar to add and addAll but you can specify the index where you would like to add the item(s).

void main() {
  var fruits = ['mangoes','bananas','apples'];
  var morefruits = ['peaches','plums'];
  fruits.insertAll(1,morefruits);
  print(fruits); //output - [mangoes, peaches, plums, bananas, apples]
}

7.getRange

Returns an Iterable of items in the range specified. You can then call toList to convert the Iterable into a list.

void main() {
  var fruits = ['mangoes','bananas','apples','peaches','plums'];

  print(fruits.getRange(1,3).toList()); //output - [bananas, apples]
}

8.fillRange

Replaces all items in the range specified.

void main() {
  var fruits = ['mangoes','bananas','apples','peaches','plums'];
  fruits.fillRange(1,4,'pears');
  print(fruits); //output - [mangoes, pears, pears, pears, plums]
}

9.lastIndexOf and lastIndexWhere

lastIndexOf allows you to get the index of the last item that you pass. This means that if you have more than one similar item/object it will get the index of the last one in the list.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums'];

  print(fruits.lastIndexOf('mangoes')); //output - 2
}

lastIndexWhere is similar to lastIndexOf except that it allows you to specify a test instead of an object/item. It then takes the index of the last item that passes the test

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums'];

  print(fruits.lastIndexWhere((item)=> item == 'mangoes')); //output - 2
}

10.shuffle

Shuffles the items in the list randomly

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums'];
  fruits.shuffle();
  print(fruits); //output - [bananas, plums, peaches, mangoes, mangoes]
}

11.sort

Sorts the items of the list based on the passed argument which is normally a Comparable

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];
  fruits.sort((a,b)=> a.compareTo(b));
  print(fruits); //output - [apples, bananas, mangoes, mangoes, peaches, plums]
}

void main() {
  var numbers= [30,10,22,45,24,88,1,37,100,0];
  fruits.sort((a,b)=> a - b);
  print(numbers); //output - [0, 1, 10, 22, 24, 30, 37, 45, 88, 100]
}

12.any

Checks the items in the list and returns either true or false depending on whether any item in the list passes the test or not.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];

  print(fruits.any((fruit)=>fruit.startsWith('a'))); //output - true
}

13.every

This is similar to any except that all items must pass the test instead of just one item.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];

  print(fruits.every((fruit)=>fruit is String)); //output - true
}

14.expand

Expands every item in the list/iterable to zero or more items. One good use of this method is to duplicate items in the list.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];
  print(fruits.expand((fruit)=> [fruit,fruit]).toList()); //output - [mangoes, mangoes, bananas, bananas, mangoes, mangoes, peaches, peaches, plums, plums, apples, apples]
}

15.reduce and fold

These combine the items of the list using the provided function and returns their combined value.

void main() {
  var numbers = [10,20,30,40,50,60,70,80];

  print(numbers.reduce((a,b)=>a+b)); //output - 360
}

fold takes in an initial value which is added to the combined value.

void main() {
  var numbers = [10,20,30,40,50,60,70,80];
  print(numbers.fold(100,(a,b)=> b+a)); //output - 460
}

16.join

Converts each item into a string, joins the passed string to all items and concatenates all items into one string.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];

  print(fruits.join(' are fruits,')); //output - mangoes are fruits,bananas are fruits,mangoes are fruits,peaches are fruits,plums are fruits,apples
}

17.map

Returns a new Iterable with every item modified to fit the passed function. You can then call toList to convert to a list.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];

  print(fruits.map((fruit)=> "$fruit are fruits").toList()); //output - [mangoes are fruits, bananas are fruits, mangoes are fruits, peaches are fruits, plums are fruits, apples are fruits]
}

18.forEach

Takes each item and applies the given function in their index order.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];
  fruits.forEach((fruit){
    print(fruit);
  });
}

19.followedBy

Adds the passed list/iterable to your list.

void main() {
  var fruits = ['mangoes','bananas','mangoes','peaches','plums','apples'];

  print(fruits.followedBy(["coconuts","guavas"]).toList()); //output - [mangoes, bananas, mangoes, peaches, plums, apples, coconuts, guavas]
}

20.take

Takes in an integer and returns a list with only the first elements up to the length specified.

void main() {
  var fruits = ['mangoes','bananas','peaches','plums','apples'];

  print(fruits.take(3).toList()); //output - [mangoes, bananas, peaches]
}

Summary

There are a few more methods that I did not outline here. They are also important and I would suggest you take a look at the official docs to better understand these methods and more. The methods outlined here are those that I often find myself looking up.

Stencil as a design system tool.

Newton Munene — Fri, 07 Jun 2019 09:34:09 +0000

Introduction

If you are a product designer you've probably heard of design systems. It's an important aspect in your field. Some front end devs already know what design systems are and are probably using them. We have all seen companies like Google, Uber, Airbnb talk about design systems and we're often left wondering, what the heck is all the fuss about.

A design system is a group/collection of components built using strict guidelines and clear standards. According to Stencil Js, A Design System(DS from now on) consists of UI components and a clearly defined visual style, released as both code implementations and design artefacts. When adopted by all product teams, a more cohesive customer experience emerges. Let's break this down.

As part of a design team at a company, you seat down to discuss the design of your next product. You quickly realise that your next product will not have the same visual appeal as your previous product, and your previous product looks nothing like your first product. The problem here is that your design is not consistent. The mobile team is creating something totally different from the web team. This is where a design system comes into play. Having a clear guideline on what your digital products should look like is really important. Here's why:

1. Saves time

When you already a DS implemented you eliminate the time taken to draft up designs and mock-ups for products. When you already have something to reference everything moves quick.

2. A fluent design

The human brain automatically feels comfortable around familiar surroundings. Let's take a logo for example. When a human sees a logo they are familiar with they will immediately recognise the entity associated with it. Same as Google's material design or bootstrap. In the same way, if you have consistent designs on your products users can immediately relate.

3. Maintenance

It's easy to maintain your product's design because the components are modular and reusable. You just have to update the component and you don't have to dive into your messy javascript code. We all write messy code at times.

And that's just the tip of the metaphorical iceberg. Do I have you hooked yet? Here's how you can implement a DS.

1. Evaluate your current design.

Take a look at your current design and decide what you want to keep and what you'd like to discard. Add whatever else is missing while at it.

2. Implement a design language/guideline.

This includes colour, fonts and typography, spacing and margins, shapes etc. Like rounded corners, some unique font, 5 px margins, the colour yellow? Implement that.

3. Decide on a pattern.

You already have what you would like to keep and a design language. Now agree on a pattern: Call to action buttons, active and inactive elements, positioning of elements, font size etc.

4. Document your components.

A wide range of people will be using your DS, so make sure the documentation is easy to follow and comprehensive.

Time to get rid of the bore. Let's get into the good stuff.

Stencil Js

This is a tool created by the team at Ionic to help them build web components for Ionic Framework internally. They eventually realised Stencil's potential and made it open to the public. It's a tool for creating web components or even whole web apps. Paired with Ionic 4 which is now universal(works with any javascript framework or no framework at all thanks to stencil js), you can build a fully optimized Progressive Web App. I will not get into web components in this post but they are what Stencil is created to achieve. I've been using Stencil since it's early beta days and just yesterday on June 6 2019, they released stencil one 🎊🎉🎆. Read more about it on their blog, https://blog.ionicframework.com/.

Prerequisites

NPM 6 or higher

Let's get started.

Fire up your terminal 💻 and run:



npm init stencil

You'll be presented with a prompt to choose what kind of project you would like and to name it.

I'd like to make a simple web component. Choose that and give it a name. I called mine ds-tutorial. cd into your project.



cd ds-tutorial

There's a lot of files and folders here so let's see what's important.

src - This is your working directory, your app lives here and this is where you will be writing most if not all of your code.
src/components - This is where your component(s) will be. There's already a default component in there.
src/index.html - This is your app's entry HTML file. Open it and you'll find the default component mentioned above used.
package.json - Defines your dependencies and some other useful information used by package providers and stencil.
stencil.config.ts - This contains the configuration for your stencil project. You can add service workers, plugins, generate docs and more. Read more about it here

The rest must be familiar to you. Stencil uses TSX, which is typed JSX. JSX is a syntax extension to javascript and is common in React. It should not scare you off. It's fairly simple to use. It allows us to write our HTML inside javascript files.

Open up your project in a text editor. Visual Studio Code has awesome syntax highlighting and tooling. Navigate to src/components/my-component/my-component.tsx and change the code to



import { Component, Prop, h } from '@stencil/core';

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true
})
export class MyComponent {
  /**
   * Your name
   */
  @Prop() name: string;

  render() {
    return <div>Hello, World! I'm {this.name }</div>;
  }
}

There's a handful going on here. If you've used angular before you'll be familiar with decorators.



@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true
})

This decorator provides metadata about our component to the Stencil compiler. I won't get into the details but you can research on decorators.

tag defines the HTML tag of your web component.
styleUrl defines the path to your stylesheet.
shadow determines if your component will use native shadow-dom encapsulation or not.

Inside your class, there's another decorator



@Prop() name: string;

This decorator defines properties which should be passed to our component. Think of these properties as attributes. There's a ton of other decorators which you can read about here.

There's finally the render function. This function outputs a tree of components that will be drawn to the screen.



render() {
    return <div>Hello, World! I'm {this.name }</div>;
  }

Save this file and open src/index.html
Just after the opening body tag, you'll find your component. Make sure the tag matches that in your my-component.tsx file.



 <my-component name="Your Name"></my-component>

Remember the name property, just like a normal attribute right 😃? Save this file and go back to your console. Make sure you're in the project's root directory and run:



npm start

Now watch the magic happen. Try changing the value of the name attribute in index.html and save. Watch what happens. The changes will be reflected immediately. And it's crazy fast. Now add some styling to src/components/my-component/my-component.css and watch. Play around with these three files. When you're done go to the console and run:



npm run build

This builds your component(s) for production and saves it in the dist folder. You can change this in stencil.config.js. You can now publish this to NPM or some other place. Add a few more components in the components folder and you have a collection of web components, a Design System 😀. Stencil handles all the hard things in the background so you can focus on the easy stuff.

Finalising

You can always visit the stencil website for more advanced concepts and usage. This was just to get you started with Stencil. There's so much more you can do using stencil. I've not even covered a quarter of what stencil is capable of. Try it out, push your imagination to the limit.

Dart getters and setters

Newton Munene — Thu, 16 May 2019 11:24:23 +0000

Prerequisites

You will need basic knowledge of

Dart
Object-Oriented Programming

Getters and setters are special methods that provide read and write access to an object’s properties. Each instance variable of your class has an implicit getter, and a setter if needed. In dart, you can take this even further by implementing your own getters and setters. If you've had any experience in Object-Oriented Programming you'll feel right at home. Let's get started.

In OOP a class acts as an Abstract Data Type(ADT) for an instance of that class(Object). In dart, this is also the case. The basic syntax for a class is:

class className {
 fields;
 getters/setters
 constructor
 methods/functions
}

The getters and setters can also be placed after the constructor. Now let's create a class and instantiate it.

class Vehicle {
  String make;
  String model;
  int manufactureYear;
  int vehicleAge;
  String color;

  int get age {
    return vehicleAge;
  }

  void set age(int currentYear) {
    vehicleAge = currentYear - manufactureYear;
  }

  // We can also eliminate the setter and just use a getter.
  //int get age {
  //  return DateTime.now().year - manufactureYear;
  //}

  Vehicle({this.make,this.model,this.manufactureYear,this.color,});
}

Age here is both a getter and a setter. Let's see how we can use it.

void main() {
 Vehicle car = 
 Vehicle(make:"Honda",model:"Civic",manufactureYear:2010,color:"red");
  print(car.make); // output - Honda
  print(car.model); // output - Civic
  car.age = 2019;
  print(car.age); // output - 9

}

One of my favourite ways of using getters is getting a Map from an object.

void main() {
 Vehicle car = Vehicle(make:"Honda",model:"Civic",manufactureYear:2010,color:"red");
  print(car.map); // output - {make: Honda, model: Civic, manufactureYear: 2010, color: red}
}
class Vehicle {
  String make;
  String model;
  int manufactureYear;
  int vehicleAge;
  String color;



  Map<String,dynamic> get map {
    return {
      "make": make,
      "model": model,
      "manufactureYear":manufactureYear,
      "color": color,
    };
  }

  int get age {
    return DateTime.now().year - manufactureYear;
  }

  void set age(int currentYear) {
    vehicleAge = currentYear - manufactureYear;
  }

  Vehicle({this.make,this.model,this.manufactureYear,this.color,});
}

That covers basic usage of getter and setters in Dart. There's is a lot more to learn about classes. I will cover everything in a future post. Also, note the use of named parameters in our constructors. I'll also cover those and other ways of passing parameters in a future post

Navigation in Flutter

Newton Munene — Wed, 15 May 2019 19:56:00 +0000

Prerequisites

All applications, complex and simple, need some form of navigation. It improves the general user experience. There are different approaches to navigation and one of the most popular among mobile apps is stacks. Flutter also uses this concept of poping and pushing pages onto a stack.

You will need to have basic knowledge of:

Dart
Widgets(Stateful and Stateless)

Named Routes

If you are a developer coming from Web development, mostly angular and react you will be familiar with route navigation. Flutter also offers this option and I find it much easier to use as the syntax is much cleaner.

You will need to define your routes in the MaterialApp widget. The routes argument takes a Map of a String as key and a WidgetBuilder as value

import 'package:flutter/material.dart';

main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      routes: {
        "/": (BuildContext context) => StartPage(),
        "/login": (BuildContext context) => LoginPage(),
        "/register": (BuildContext context) => RegisterPage(),
        "/home": (BuildContext context) => HomePage(),
      },
    );
  }
}

CAVEAT: When you specify the root route ("/") you should not specify the home widget.

You can then call Navigator.pushNamed(BuildContext context, String routeName) or Navigator.of(BuildContext context).pushNamed(String routeName)
This will add a new page to the top of the stack.

import 'package:flutter/material.dart';

class StartPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Container(
        child: Center(
          child: RaisedButton(
            child: Text(
              'Go To Home Page',
            ),
            onPressed: () {
              Navigator.pushNamed(context, "/home");
            },
          ),
        ),
      ),
    );
  }
}

To go back to the previous page you can call Navigator.pop(BuildContext context) or Navigator.of(BuildContext context).pop()
You can also use Navigator.pushReplacementNamed(BuildContext context, String routeName) to clear the stack and push a new page onto it. This means that you can't go back.
Here are some more code samples:

Navigator.pushNamed(BuildContext context, String "/home");
Navigator.of(BuildContext context).pushNamed(String routeName);

Navigator.pushReplacementNamed(BuildContext context, String routeName);
Navigator.of(BuildContext context).pushpushReplacementNamedNamed(String routeName);

Navigator.pop(BuildContext context);
Navigator.of(BuildContext context).pop();

onGenerateRoute

An alternative to having a routes argument in your MaterialApp widget would be onGenerateRoute. This generates your routes dynamically.

import 'package:flutter/material.dart';

main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      onGenerateRoute: (RouteSettings settings) {
        switch (settings.name) {
          case '/':
            return MaterialPageRoute(builder: (context) => StartPage());
            break;
          case '/home':
            return MaterialPageRoute(builder: (context) => HomePage());
            break;
        }
      },
    );
  }
}

You can then navigate just like named routes.

Navigator.pushNamed(BuildContext context, String "/home");

MaterialPageRoute

You don't need to have your routes defined to use this method. Because I'm from a Web background I prefer the former method but this one is also important.

import 'package:flutter/material.dart';

class StartPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Container(
        child: Center(
          child: RaisedButton(
            child: Text(
              'Go To Home Page',
            ),
            onPressed: () {
              Navigator.push(
                  BuildContext context,
                   MaterialPageRoute(
                      builder: (context) =>  HomePage()));
            },
          ),
        ),
      ),
    );
  }
}

Just as Named routes you can also call pop to go back in the stack and pushReplacement to clear the stack and add a page as the top of stack.

Navigator.push(BuildContext context,MaterialPageRoute(builder: (context) =>  
HomePage(),),);
Navigator.pushReplacement(BuildContext context,  MaterialPageRoute(builder: (context) =>  
HomePage(),),);
Navigator.pop(BuildContext context);

That's about it for the basics. Flutter takes care of page transition animations for Android and IOS so you can focus on the important parts. In future posts I will cover:

Custom page transitions
Passing data back and forth

Thank You.

I am a Mobile and Web Developer, Ask Me Anything(anything Flutter, anything Javascript)!

Newton Munene — Wed, 15 May 2019 18:19:30 +0000