DEV Community: Curious Paul

Build a Product Review Tool For Telegram Bot Using Appsmith

Curious Paul — Wed, 22 Jun 2022 12:55:52 +0000

"Telegram-Business" is a Telegram bot that connects customers to small-scale businesses. Users can either sign up to use the bot as business owners and create a catalog for their products or use it as customers looking to purchase something from businesses on the bot. It works a lot like the popular 'Whatsapp Business' platform.

In this article, I will teach you how to use Appsmith to build a product review tool for a Telegram bot. Think of this as a proof of concept of how Appsmith can help small businesses by automating some aspects of their businesses. More specifically, with this app, users can add reviews on products they've used to help others make wise decisions when purchasing, and business owners can take the feedback given to make their products more consumer-friendly.

If you want to see how I built the Telegram bot you can check this article I wrote about it here.

Prerequisites

To follow along with the article steps, you should have the following setup:

Appsmith Account: You can create an account with Appsmith for free via this link.
Also, be sure to read the tutorial on how to create a telegram bot via this link.

Overview of the Tool

The process starts by creating a new application on Appsmith, and designing the interface for the product review tool using the available widgets in the design area, as shown below:

This utilizes the rating widget for the star rating, the text widget to display the product description, image widget to show an image of the product, and input widget for the comment that the user may want to leave on the product as part of their review, and of course a button widget to submit the review.

We also want users to see comments made by other people on the product, so we'll design a second portion of the interface right beneath this one, as shown below:

This portion consists of a text widget which describes the section "what others are saying", followed by the list widget, which has been emptied and contains only a text widget to display the comments by other users. It's empty at the moment so it seems bare, however, once the data kicks in it'll come to life. You can choose to add an outline to the input field to make it more visible as shown below:

Adding Datasources

We'll start by creating an API to fetch data to display on the list widget from the bot's database; which is hosted by Fauna which is a serverless database provider, that also provides us with a graphql API through which we can send queries directly to the database.

We will be querying the database via this graphql api from our Appsmith application. Head over to the "Queries/JS" section and choose to create a new "Blank API", and add the following details to this new api:

Name: getProduct
URL: https://graphql.fauna.com/graphql
method: POST
Headers:
- Authorization: Bearer
body:

{{

    JSON.stringify(
        {
            variables: null,
            query: `
                query {
                    findProductByID(id: "${appsmith.URL.queryParams.product_id}")
                    {
                        name
                        image
                        description
                    }
                }
            `
        }
    )
}}

Once you're done your API should look like this:

You will observe that in the body of this API we make use of the "findProductByID" graphql query made available to us via FaunaDB.

Inside of this query we must specify a product id, namely the product id of the product that is to be reviewed, that way we can fetch the information about the product including the product image and description, which we can then display on our interface via the image widget and text widget.

id: "${appsmith.URL.queryParams.product_id}"

That is what this line does in the query, we fetch the product id from the Context object that Appsmith provides us with.

The Context object contains a number of properties of any Appsmith application that help us store and reference information about our application, for example, the famous "store" object is a part of the context object and we can use it to store information in our application's local store. Here's a list of items available in the Appsmith context object:

You can find out more about the context object here.

Meanwhile, the item of interest for us here is the "URL" object from the context object, which holds information about our application's URL, including the hostname, and query parameters amongst other things, as shown below:

This is important to us because we will be passing in information about the product to be reviewed and the user issuing a review as query parameters to our application url, namely the "product id" and the "user id" from the bot. This will make more sense when we integrate the application with the telegram bot.

getReviews API

Next, let's add another API that will fetch all the reviews on the given product. So head to the "Queries/JS" section again and choose to create a new API this time with the following details:

Name: getReviews
URL: https://graphql.fauna.com/graphql
method: POST
Headers:
- Authorization: Bearer
body:

{{

    JSON.stringify(
        {
            variables: null,
            query: `
                query {
                    findReviewByProductID(product_id: "${appsmith.URL.queryParams.product_id}")
                    {
                        data {comment}
                    }
                }
            `
        }
    )
}}

Here we send a query to the bot's database to fetch all reviews from the "Reviews" table that are associated with the given product's id, which is also gotten from the URL query parameter as with the previous API.

send_review API

This API is what will handle the creation of new reviews which plays a vital role in our application since that's the main purpose of the application. This API unlike the rest utilizes a graphql mutation (also provided by the FaunaDB graphql API for the bot's database). Below are the details of this API:

Name: send_review
URL: https://graphql.fauna.com/graphql
method: POST
Headers:
- Authorization: Bearer
body:

{{

    JSON.stringify(
        {
            variables: null,
            query: `
                mutation {
                    createReview (data: {
                        chat_id: "${appsmith.URL.queryParams.chat_id}"
                        stars: "${Number(Rating1.value)}"
                        comment: "${Input1.text}"
                        product_id: "${appsmith.URL.queryParams.product_id}"
                    })
                    {
                        _id
                    }
                }
            `
        }
    )
}}

As you can see in this mutation query, we reference the data from some of the widgets, including the rating widget, for the value of the ratings that are given. And the "input" widget, which holds the comment given by the user on the product. Also, observe that we fetch the user's telegram id (chat_id) from the URL to associate the new review with that particular user.

Connect Datasources To Widgets

Next, we must connect the APIs we've created to the interface via some of the widgets. First, off we want the user to be able to send in a review to the database once they click on the "submit review" button, so to do that, we will open up the properties of the button by clicking on the settings icon next to it, and choose an OnClick action for the button.

Head over to the submit button widget and bring up the settings pane, and under the Actions section, choose the option to Execute a query and then select thesend_review` API from the list of options shown, as shown below:

Not only do we specify an "onClick" action, but we also specify an onSuccess action, which simply brings up a modal that displays a success message, like the one shown below:

This is a simple modal with just two Text widgets, so you can create one like that and link it to the onSuccess action as I have done.

Next, we must feed data to the list under the "What others are saying" section; click on the widget to bring up the settings for the list. Under the " items" option, add the following to load the data from our getReviews API:

This will load data from the query onto the list widget as a list of JSON objects. However, we must still specify what data goes where for each list item. In our case, we must specify what data from the "current object" goes to each list item's Text widget. Recall that each list item has a "text" widget in it, so for that text widget, we will specify its "Text" property to be the following:

Lastly, we must add data to the Image widget and the Text widget that holds the product's description. For the image, we'll set the "image" property to the following:

Here, I am calling the "getProduct" API, which we created earlier on, and fetching the data from the response of the API call. For the description text widget, we'll set the "text" property to something similar:

{{getProduct.data.data.findProductByID.description}}

Now that we are done with this, we can deploy the application and fetch the URL. So I'll click on the Deploy button to deploy the application, wait for it to load up completely, then copy the URL from the browser.

As observed, the application currently has no data in it because necessary arguments for the APIs getProduct and getReviews are not yet present, namely:

user_id
product_id

If you recall, these two parameters were taken from Appsmith's URL context object, which holds information about the current URL of our application - including any query parameters that may be present.

This is important because I will be passing these two arguments as query parameters to our Appsmith application.

Integrate With The Telegram Bot

This brings me to my next stop, which is to implement some logic from the bot to help users who want to leave reviews access my application.

For this, I will send a message containing the link to our Appsmith application, along with the query parameters, which would contain the "ID" of the product they want to review and their user id on telegram (chat_id) to whoever is interacting with the bot.

Note: The code snippets shown below do not show the full implementation of my telegram bot; if you want to see how I built it, kindly refer to this article.

Typically, when users come to the bot, they get multiple options when viewing products in a catalog, as shown below:

As observed I have added a last option which allows them to Add Product Review, in order to handle that I wrote a handler function that will send back a message containing the Appsmith URL with the product id and their chat_id in the URL as query parameters. Observe:

    appsmith_url = "https://app.appsmith.com/app/review- 
    product/review-6179715eb2db5a27f21af7e5"
    product_id = data.split(';')[1]
    # generate link to appsmith UI
    bot.send_message(
       chat_id=chat_id,
       text="Kindly click on the following link to head over to 
       the review page "
       f"{appsmith_url}?chat_id={chat_id}&product_id={product_id}"
     )

The appsmith_url variable holds the URL for our deployed Appsmith application, and contains no parameters, so opening that would just display a "bare" version of the interface we designed. However, notice how i append the ?chat_id={chat_id} option along with the product_id={product_id} option to the URL before sending it.

That way the user gets a response that's customized to include their personal id and the id of the product they wish to review. As such, when they click on the URL our Appsmith APIs will be able to fetch the data they need from the context object and react accordingly. Here's what a typical response from the bot looks like:

Now when they click the link, it'll take them to the Appsmith tool we created but this time with data loaded in, as shown below:

This way, my users can also leave comments on the products, and see reviews on the product, further increasing the trust that they have in the platform and in small scale business ventures.

Conclusion

I hope you enjoyed reading that!, this article has shown you how to use the Appsmith context tool as well as how to send GraphQL queries on Appsmith, via the API editor, and ultimately how to build a simple product review tool for any use case you might have.

I invite you to use what you've learned from this article to build more interesting versions of what I have built or even different tools if you wish, rest assured everything you need to fast-track your development is available to you on Appsmith.com. If you wish to see the code base for my bot you can find it on GitHub here.

Adding Two-Factor Authentication Layer To Appsmith Using TypingDNA

Curious Paul — Thu, 21 Apr 2022 14:43:53 +0000

This article is a detailed guide on adding a layer of protection to your Appsmith applications, using TypingDNA to prevent malicious sign-in attempts into your applications.

Two-factor authentication comes in many folds, and you most likely have had to validate your sign-in using an OTP (one-time-passphrase) sent via SMS or perhaps via email. All of these classify as two-factor authentication since they add one extra level of protection to resources on the web. This article will look at a "not so common" way of adding two-factor authentication to Appsmith applications.

What is TypingDNA?

TypingDNA provides behavioral typing biometrics authentication using sophisticated machine learning algorithms to monitor and verify end-users based on their "typing pattern." Using TypingDNA, we can "recognize" users by how they type.

TypingDNA monitors the typing pattern of whoever is trying to log into a system and can tell whether or not it's the same user trying to log in or if the user is being impersonated by observing their unique typing pattern.

This authentication method makes for an excellent 2FA option since we can pick bad heads right from when they're typing in to get access to our application. It's also cheaper to implement than regular 2FA that involves SMS (which, as you can imagine, would involve SMS charges).

Getting Started With TypingDNA
Pre-requisites
Building A Backend Server Using Flask and Heroku
Interfacing With Appsmith
Testing
Conclusion

Getting Started With TypingDNA

To use the functionalities that TypingDNA provides, we must first create an account with them and retrieve access keys that will allow us to interact with the TypingDNA API. To sign up for a new account, simply head to the TypingDNA website and click on the Dev Account option.

Once you're all set up, log in to your dashboard, and take note of the Authentication API Credentials section, which contains essential keys that we will be using in the following sections to interact with the TypingDNA API.

For demonstration, we will build a simple authentication flow that involves sign-up, sign-in, and the second layer of authentication using TypingDNA on a simple dashboard built on Appsmith.

More specifically, a user, who is logged into the platform, has to take the typing biometrics test before they are allowed to be logged onto the platform.

TypingDNA provides two effective options for typing pattern matching:

Same Text: this option allows us to verify how the user types given that they type the same text each time they try to authenticate, as opposed to just generally observing their typing pattern across different texts. An example would be to monitor their typing pattern as they type their email and password (which is unique) and would be the same for every login attempt they make. Pattern matching over the same text allows for even more streamlined authentication wherever it is possible to use it. So when a user's typing pattern is first "enrolled" with TypingDNA using this option, their subsequent typing patterns are checked against their typing pattern for the same text, so trying to log in with an unrecognized credential would fail.
Any text: with this option the user's typing pattern is observed as they type various kinds of texts, and is not particular to any kind of text (as is the case with SameText). Here the text used to enroll a user's typing pattern need not be the same as their subsequent typing patters for authentication.

For demonstration in this article, we will be using the SameText option to verify users' typing patterns by observing how they type in their "email" and "password."

Pre-requisites

To follow along with this guide, you will need to have the following set up:

Python3: Working python installation of versions below v3.9 .
TypinDNA account: You need to create a TypingDNA account to be able to interact with its API - look at the previous section for instructions on how to do this.
Appsmith account: You can create an account with appsmith via this link
Heroku account and CLI: You will also need to have an account with Heroku, which is where we'd be deploying the backend server to, as well as its command line interface tool. You can sign up for a free account via this link. Follow these instructions to install the heroku cli tool

Building A Backend Server Using Flask and Heroku

We'll start by creating a new folder to host our backend application; you can call this whatever you want - mine is called demo. Navigate to this folder from the terminal and create the following files

app.py: this is where we will write all of our server's code including things like route declaration, and configuration of the server.
Procfile: the Procfile is a requirement for deploying applications to Heroku, and we will be making some specifications about the kind of application we want to deploy inside of it.
models.py: here is where we'll be defining database models for our backend application.
sendtp.py: this file contains a helper function that sends requests to TypingDNA API on our behalf.
runtime.txt: this file holds specification for the version of python that we want Heroku to use in running our application in the cloud.

We'll also add two subfolders inside of the project directory templates and static. The templates folder will hold HTML files and the staic folder will contain script files essential to the operation of the server. Inside of the templates subfolder create the following:

index.html: this file will contain a simple form, that will help us record the user's typing pattern once they type inside of it, and is served by the backend server in app.py. It will be displayed whenever the user tries to login to the Appsmith application.
404.html: this file is displayed whenever we can't find a certain resource on our server. Its purpose will be made apparent in the later parts of this tutorial.

Next, we have the static sub-folder which contains javascript files as follows:

typing-visualizer.js: from TypingDNA this file is a dependency for certain UI interactions on the typing biometrics form. Copy and paste the code for this file from here
autocomplete-disabler.js: from TypingDNA, this file disables autocomplete on the typing biometrics form, because we of course always want to record the users typing pattern and using autocomplete defeats that purpose, which is why this is important. Copy and paste the code for this file from here
typingdna.js: from TypingDNA, this file is the main dependency for this project, and actually contains the typing pattern recorder as well as other methods that make typingDNA work on the form. Copy and paste the code for this file from here
index.js: in this file is where we will make use of these dependencies to make our form interactive, and use it to record typind patterns and send them to our server to process and send to TypingDNA API.

after doing this your project folder should look like the following:

core/
|__templates/
|   -index.html
|   -404.html
|__static/
|   -typing-visualizer.js
|   -autocomplete-disabler.js
|   -typingdna.js
|   -index.js
|__app.py
|__models.py
|__sendtp.py
|__Procfile
|__runtime.txt

While we're in this folder from the terminal, let's create a new virtual environment using the python package virtualenv

virtualenv env

Once this is done, activate the virtual environment as follows:

source server/bin/activate

or if you're on windows:

.\server\scripts\activate

Once you do this you should see your current file path on the terminal prefixed with the name of the virtual environment in parentheses.

The next thing we want to do is to install a number of python dependencies for this project, and we can do that from the terminal using the pip package manger as follows:

pip install flask flask-sqlalchemy psycopg2 gunicorn flask-cors

This will install all of the libraries we've listed out in order. Once they're installed, we can begin to add some code for our server inside the app.py file. Open the file and add the following lines of code to it.

from flask import Flask, render_template, request
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.exc import IntegrityError
from werkzeug.security import check_password_hash
from flask_cors import CORS
from sendtp import send_typing_data
import os

base_dir = os.path.abspath(os.getcwd())

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = f"sqlite:///{base_dir}/database.db"
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
app.config['SECRET_KEY'] = os.getenv('secret')
CORS(app)

db = SQLAlchemy(app)
from models import *
db.create_all()


@app.route('/sign-up', methods=['POST'])
def register():
    data = request.get_json(force=True)
    new_user = User(data)
    try:
        db.session.add(new_user)
        db.session.commit()
        resp =  {
            'status': 'success',
            'msg': 'user created successfully'
        }, 201
    except IntegrityError:
        resp = {
            'status': 'error',
            'msg': 'User with email {} already exists'.format(data['email'])
        }, 400
    return resp

@app.route('/sign-in', methods=['POST'])
def login():
    data = request.get_json(force=True)
    # find user
    user = User.query.filter_by(email=data['email']).first()
    if not user:
        return {
            'status': 'error',
            'msg': f"No user with email {data['email']}"
        }, 400
    if not check_password_hash(user.password, data['password']):
        return {
            'status': 'error',
            'msg': f"Password incorrect"
        }, 401
    return {
        'status': 'success',
        'msg': 'Logged in successful'
    }, 200

@app.route('/sendtypingdata', methods=['POST'])
def sendtypingdata():
    data = request.get_json(force=True)
    res = send_typing_data(data['user_tid'], data['pattern'])
    return res


@app.route('/2fa/<email>')
def twofa(email):
    # find user with email
    user = User.query.filter_by(email=email).first()
    if user:
        return render_template('index.html', user_tid=user.typing_id)
    else:
        return render_template('404.html', email=email)

if __name__ == '__main__':
    app.run()

Here we have declared four routes, including the ones for sign-up and sign-in, as well as the /sendtypingdata route which simnply sends a request to TypingDNA using the helper function in sendtp.py file which we will see in a moment.

The other important route in this is the 2fa/<email> route - this route simply renders a page called index.html from the server and passes the user's typing id as a context variable to the page.

We will see why we need to do this in a moment, when we're building the Appsmith application.

Note : Implementing TypingDNA doesn't imply that we don't need regular authentication in our backend system, even though it is possible to use it that way. However, it is advised to use it as a second layer of authentication (2FA) after you must have first validated a user's login credentials from your server, which is why we, of course, still need to add sign-up/sign-in endpoints to our server as in the code snippet above.

Next we'll add the following to the models.py file to define the database model for a user.

from app import db
from werkzeug.security import generate_password_hash
import uuid

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True, nullable=False)
    name = db.Column(db.String())
    email = db.Column(db.String(100), unique=True)
    password = db.Column(db.String())
    typing_id = db.Column(db.String(), default=str(uuid.uuid4()))

    def __init__(self, *args) -> None:
        super().__init__()
        if args:
            params = args[0]
            for key, val in params.items():
                if key.lower() == 'password':
                    setattr(self, key, str(generate_password_hash(str(val))))
                else:
                    setattr(self, key, val)

Next, we'll add the code for the sendtp.py file which just contains a helper function that sends a request to TypingDNA on our behalf.

import urllib.request
import base64
import os
import json

base_url = 'https://api.typingdna.com'
apiKey = os.getenv('tpkey')
apiSecret = os.getenv('tpsecret')



def send_typing_data(user_id, pattern):
    authstring = f"{apiKey}:{apiSecret}"
    base64string = base64.encodestring(
        authstring.encode()).decode().replace('\n', '')
    data = urllib.parse.urlencode({'tp': pattern})
    url = f'{base_url}/auto/{user_id}'

    request = urllib.request.Request(url, data.encode('utf-8'), method='POST')
    request.add_header("Authorization", f"Basic {base64string}")
    request.add_header("Content-type", "application/x-www-form-urlencoded")

    res = urllib.request.urlopen(request)
    res_body = res.read()
    return json.loads(res_body.decode('utf-8'))

This is the function that is called in the /sendtypingdata route from the code in the app.py file as shown below:

@app.route('/sendtypingdata', methods=['POST'])
    # code omitted for brevity
    # ..
    res = send_typing_data(data['user_tid'], data['pattern'])
   # ..

The function takes in two arguments, a user's "typing id" and a the user's typing pattern. Every user is given a unique "typing id" upon signing up. This is done so that we can safely and uniquely match each typing pattern with the corresponding user.

So whenever we send a request to TypingDNA API to verify a user based on their typing pattern, we must send along this typing id that's associated with the user, that way TypingDNA can check to see if the pattern we're sending matches with the previously saved pattern for that particular "typing id", and if it does, we will get a positive response from the API, and we can then allow the user to access the application.

Building The Typing Biometrics Form

Let us now add the code for the typing biometrics form, which will contain two fields asking for email and password from the user who has just attempted to log in or is just signing up.

In the index.html file in the templates/ folder we created earlier on, add the following:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <link
      rel="stylesheet"
      href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css"
      integrity="sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh"
      crossorigin="anonymous"
    />
    <link
      rel="stylesheet"
      href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css"
      crossorigin="anonymous"
    />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <script type="module" src="{{url_for('static', filename='index.js')}}"></script>
</head>
<body>
    <form id="typing-patterns-form" style="width:80%;margin:0 auto">
        <h3 align="center">Typing Biometrics 2FA</h3>
        <p align="center">Please type your username and password again.</p>
        <div class="form-group">
          <label for="email">Email Address</label>
          <input
            type="email"
            class="form-control disable-autocomplete"
            id="email"
            name="email"
            placeholder="Enter email"
          />
        </div>
        <div class="form-group">
          <label for="password">Password</label>
          <input
            type="password"
            class="form-control disable-autocomplete"
            id="password"
            name="password"
            placeholder="Enter password"
          />
        </div>
        <br />
        <button type="button" id="typing-patterns-btn" class="btn btn-primary">
          Submit
        </button>
      </form>
      <input type="hidden"  id="user_tid" value="{{ user_tid }}">
      <script>
        var id = document.querySelector("#user_tid").value;
        console.log(id);
        localStorage.setItem('user_tid', id);
      </script>
</body>
</html>

Observe that I have linked the index.js script to this HTML file at the top so that we can use the TypingDNA libraries to interact with the form on this page and record the user's typing pattern.

I have also embedded/stored the user's typing id from the server onto a hidden "input" tag and local storage; this will allow the user to reference the user's way of typing every time the user's typing pattern is being sent to the TypingDNA API.

Note: The index.html page is going to be loaded into an iframe on Appsmith and since it is being rendered from our server as opposed to Appsmith which is of a different domain, the localstorage of the iframe would be different from that of our Appsmith application, and we won't be able to store or retrieve anything from it using Appsmith store object. Which is why I am setting the localstorage from inside the index.html file which is on the same domain as my server, that way I can access it from within the iframe later on.

Next, add the following to the 404.html file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title></title>
</head>
<body>
    <h1>NOT FOUND</h1>
    <p>
        user with email {{email}} was not found.
    </p>
</body>
</html>

This is displayed whenever a user attempts to login with an email that hasn't been registered yet.

Next in the index.js add the following lines of code:

import { TypingDNA } from "./typingdna.js";
import { AutocompleteDisabler } from "./autocomplete-disabler.js";

const tdna = new TypingDNA();

const autocompleteDisabler = new AutocompleteDisabler({
  showTypingVisualizer: true,
  showTDNALogo: true,
});
autocompleteDisabler.disableAutocomplete();
autocompleteDisabler.disableCopyPaste();

const typingPatternsButton = document.getElementById("typing-patterns-btn");
const email = document.getElementById("email");
const password = document.getElementById("password");
const id_obj = document.querySelector("#user_tid").value;
const frm = document.getElementById('typing-patterns-form');
var payload = {};

typingPatternsButton.addEventListener("click", () => {
    const text = email.value + password.value;
    tdna.addTarget("email");
    tdna.addTarget("password"); 
    sendPattern(text);
});


function sendPattern(text){
    const pattern = tdna.getTypingPattern({
        type: 1,
        text: text
    })
    if (id_obj.length > 0){
      payload = {pattern: pattern, user_tid: id_obj};
    }
    else {
      console.log(id_obj);
      console.log(id_obj.length);
      payload = {pattern: pattern, user_tid: localStorage.getItem('user_tid')};
    }
    console.log(payload);
    fetch("/sendtypingdata", {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        credentials: 'include',
        body: JSON.stringify(payload)
    })
    .then((response) => response.json())
    .then((data) => {
        console.log(data);
        if (data.message_code == 10) {
          alert(
            "In order to verify your identity, you will be required to fill this form a couple of times."
          );
          frm.reset();
        } 
        else {
          if (data.result == 1) {
            alert(
              "TypingDNA indicated that there was HIGH confidence in your login pattern"
            );
            window.parent.postMessage('Verified', '*');
          } else {
            alert(
              "TypingDNA indicated that there was LOW confidence in your login pattern"
            );
          }
        }
      });
    tdna.reset();
}

Here we take the inputs from the two fields and then concatenate the two strings into one and pass them to the TypingDNA.getTypingPattern() method. This method is responsible for recording the typing pattern of the user and takes in two arguments:

type: which specifies the type of pattern matching we want to use, which in this case is "SameText", we specify this using the value of 1 (for SameText), and 0 for "anyText" matching.
text: the typed string that we want the typing pattern for, which is .

This function generates the pattern in a data form that the TypingDNA API can understand. We then pass this pattern to our flask server on the "/sendtypingdata" endpoint, which utilizes the helper function in sendtp.py to send a request to TypingDNA to record and validate the user's typing pattern.

We also send the user's typing id, which can be retrieved from the hidden input tag on the form page or local storage.

Deploying To Heroku

The next thing we have to do is to deploy the server to Heroku, to do this we must make some specifications for the deployment first however. In the Procfile file, add the following:

web: gunicorn app:app

This tells Heroku how to run our application. Here, we have specified that to run our application Heroku needs to use the "gunicorn" command and use the name "app" to reference the target application, which is indeed called "app.py."

The Procfile deployment specification follows the format of

[process_type]: [command]

The next thing is to specify the python version we want to use using the runtime.txt file. Head over to your cmd or terminal and type:

python --version

python3 --version

This will show you the python version you currently have installed, and in my case, this is shown below:

Here it shows that I currently have python version 3.8.8 installed. It may or may not be different in your case, but you need to take note of the version number, so that we can use it to specify what version you want to use to deploy your application.

Important: Make sure you're using a python version lower than v3.9+. This is because one of the functions from a library used in the code snippet for sendtp.py has been deprecated in versions 3.9+. This is the base64.encodestring() method, and has been deprecated in 3.9+, you can of course find a work around, but for the purposes of demonstration, we will just use the library as it is.

Head over to the runtime.txt and specify your python version as follows:

python-<your.version.number>

Make sure to specify all the three version number components (major, minor, and patch), the letters are case sensitive and no spaces should be in between the version numbers. Once you're done your runtime specification, should look like the one shown below:

python-3.8.8

Creating A Heroku Application

Once you have the Heroku cli tool installed, open up a new terminal and navigate to the project directory, and login using the command:

heroku login

This would prompt you to open your browser and log you in from there, by the time its done you should be logged in from the terminal as well, you can now create a new heroku app as follows:

heroku create tpdemo

I called mine tpdemo, you can give yours any name as well. Since Heroku doesn't allow shared names you might have to come up with a much cooler name than mine.

Another important thing we must do is to set some environment variables to hold our TypingDNA credentials from earlier. We can directly set environment variables into our Heroku application from the cli as follows:

heroku config:set <ENV_NAME>=<ENV_VALUE>

Using this format, we must set two environment variables, which is required to send API requests to TypingDNA. Copy your TypingDNA "api key" and set it as the value to an environment variable called "tpkey", copy the "API secret" as well and set it as the value for an environment variable called "tpsecret".

heroku config:set tpkey=jheyu123****khd54***jh

Before we finally deploy we must tell Heroku, of the things it needs to install before running the application, and this is done using a requirements.txt file which Heroku will automatically look for during deployment.

We can easily append the requirements from our virtual environment using pip as follows:

pip freeze>requirements.txt

This will take all of the installed dependencies in our virtual environment and add them to a file called requirements.txt, so you should find that it created a new file for you by that name that has the following contents, or at least similar contents:

certifi==2021.10.8
charset-normalizer==2.0.12
click==8.0.4
colorama==0.4.4
Flask==2.0.3
Flask-Cors==3.0.10
Flask-SQLAlchemy==2.5.1
greenlet==1.1.2
gunicorn==20.1.0
idna==3.3
itsdangerous==2.1.1
Jinja2==3.0.3
MarkupSafe==2.1.1
psycopg2==2.9.3
PyYAML==6.0
requests==2.27.1
six==1.16.0
SQLAlchemy==1.4.32
urllib3==1.26.9
Werkzeug==2.0.3

To deploy the application, we will be using git, so head back to the terminal and initialize a git repository in the project folder using the init command, and then add and commit the changes to version control history.

Now we will add a remote origin for the Heroku application, so that we can push and in effect deploy the application from the terminal using git.

heroku git:remote -a <Your-heroku-app-name>

This will create a private repository on heroku that your updates will be pushed to when you push your changes to Heroku. Now we can finally deploy our application by pushing the committed code as follows:

git push heroku main

This would begin the deployment operation with logs similar to these:

Once its done it should give you a link to the application instance, this link is usually of the format: (your-app-name).herokuapp.com. Copy this link and paste it in a browser, and add any of the url prefix for any of the endpoints on the server like /sign-up for example

We see that the request goes through, and this is sign that the server is up and running and is accessible publicly. Now let's head over to appsmith and build the interface for our authentication.

Interfacing With Appsmith

To begin with you want to login to your Appsmith dashboard and create a new application, this should bring you to the development environment like the one shown below:

This environment is where we'd be building our "application," and it's mostly a drag and drops environment with widgets and other build tools on the left pane, and the broader space to the right is the development area where you drag widgets on.

Drag and drop a tab widget onto the right pane, and resize it to your taste. The tab widget has two tabs inside it by default called "Tab1" and "Tab2". We're going to be using them for the sign-up and sign-in interfaces, so rename them to "sign-up" and "sign-in" so that your tab widget looks like the one shown below:

Next we will create a form using the form widget for the "sign-up" tab, this form will allow new users to sign-up for an account with the application just like every normal application. Remove one of the two buttons that come with the form, since we only need to use one button to submit a sign up. You can also adjust the "border color" as well as the "border width" of the form, to make it more visible.

Drag the form widget onto the sign-up tab. On the form widget we'll drag and drop input widgets onto it to collect the information we need for sign-up including Name, Email, and Password.

For each of these input widgets we can edit the properties using the settings option on each widget, on the right side of the window. Look for the option that says "Data Type" and change the data type for email and password input fields to "email" and "password" respectively.

Also use the placeholder property to set a placeholder text for each input field.

Set the "Reset Form on Success" property on the form submit button to false, by toggling the switch. This will allow us access the form data for further use after sign-up as we will later on see, when we add the iframe widget.

Lastly, we want to make sure that the length of the password entered is long enough, and we do this to make sure that TypingDNA has enough data to monitor. According to the TypingDNA documentation it is recommended that the total length of characters in both the email and password be 30 or more characters in length for "SameText" pattern matching. We can't control what the email length is, but we can with the password.

We can control this by using the "Valid" property on the input widget setting on the right side of the window. Inside this property we will write the following moustache syntax to specify that we want the length of whatever password is typed to be greater than or equal to 8.

{{Input3.text.length >= 8}}

Add this inside the "Valid" option field, and it will automatically raise an error if the password is less than eight characters in length.

After all this is done your form should look something like the one below:

Click on the "sign-in" tab and create a sign in form with input fields for "email" and "password" only. Add similar properties for these fields as with the email and password from sign up form. Make sure to also set the "Reset Form on Success" property on the sign-in form submit button to false, by toggling the switch.

Adding Two-Factor Authentication Modal

While you're still on the sign-in tab, drag another widget onto the drawing area - a modal widget. This widget is like a pop-up that will show up whenever a user has just finished signing up or is trying to login, inside of this modal is where we prompt them to take the Typing biometrics test. Remove the two buttons in the modal since we won't be using them.

Rename the modal to "sign_in_modal" we will use this name to reference it later on. Also change the title inside it to Typing Biomnetrics or anything you want really.

Inside of the modal we will now add an iframe widget which will load the typing biometrics form, and record their typing pattern. You may want to increase the size of your modal to fully accomodate the iframe widget, adjust it accordingly so that it looks like this:

Modify the Iframe url to point to the Heroku server url instead on the /2fa/<email> endpoint. The part will come from whatever email the user typed into the email field which is why we disabled the form reset on submit earlier on. We can specify this using Appsmith's moustache syntax as follows:

Input4 is the email field for the sign-in form which we're currently on.

Next we want to add an onMessageReceived handler to the iframe's properties. What this will help us do is to automatically redirect the user to the protected application once TypingDNA API verifies the typing pattern.

This is possible because in the index.js file we have also specified that the iframe send a message to the parent page (the page on which the iframe sits on ) once we get a positive feedback indicating a match with the user's typing pattern.

// code omitted for brevity
// ..
if (data.result == 1) {
    alert(
        "TypingDNA indicated that there was HIGH confidence in your login pattern"
    );
    window.parent.postMessage('Verified', '*');
}
// ..

Appsmith can listen for this message and we can setup a handler for when this event happens, or more specifically when the iframe sends a message. We do this using the onMessageReceived handler in the iframe's properties. Click on the dropdown and choose the option to
"navigate to" a different page.

Here I specified a page called "App" which we will create in a moment.

Once you're done with this head back to the sign-up tab and create a similar modal call this one "sign_up_modal", with its own iframe, and url set to your heroku url followed by the "/2fa/" route, for which the part of this route should correspond to the email typed into the email field on the sign-up form which in my case is "Input2.text".

Also add the same onMessageReceived handler for this iframe as with the first one. At the end you should have two modals in your widgets section as shown below:

Implementing Form Handlers On Appsmith

Let us now add some handlers for the sign-up and sign-in forms that we've just created. Head over to the explorer tab and under the Queries/js section click the plus icon to create a new query or javascript object. We will be creating two API objects and a javascript object in this case.

Select the "New Blank API" option to create a new API. It should take you to a new screen where you can edit the properties sof your API as shown below:

Edit the API name to "sign-up", and change the request type from "GET" to "POST", also paste in your Heroku url, and append the suffix route which is "/sign-up" as defined in our flask server. In the body of the request add following to create a payload that contains data from the sign-up form.

{
    "name": {{Input1.text}},
    "email": {{Input2.text}},
    "password": {{Input3.text}}
}

Once you're done the API should look like mine below:

Create a second API, this time called "sign_in", with a "POST" request and the url should be /sign-in, similar to how it was with the sign-up API. The body for this request should be as follow:

{
    "email": {{Input4.text}},
    "password": {{Input5.text}}
}

Note: If for some reason your input fields aren't numbered in order like with mine, use the correct input widget labels for your case instead of the ones shown. For example if in the sign-in form, your password field is numbered as "inpur7", then you must use input7.text in your request body for the "password" value.

Finally head back to the "Queries/Js" section in the explorer pane again, but this time select the "New Js object" option from the options showed, to create a new javascript object.

This should bring you to an edit screen, where you can edit the code for your javascript object. Replace the default code snippets in there with the following:

export default {
    sign_up: async () => {
        return sign_up.run()
        .then(() => showModal('sign_up_modal'))
        .catch(e => showAlert(e.message, 'error'))
    },

    sign_in: async () => {
        return sign_in.run()
        .then(() => showModal('sign_in_modal'))
        .catch(e => showAlert(e.message, 'error'))
    }
}

Inside this JS object, I have defined two functions "sign_up" and "sign_in", which just execute the APIs whenever either one is called, and if we get a positive response from the server it opens up the modal, where we can see the iframe that prompts us to take the typing biometrics test.

Notice that the sign_up function calls the "sign_up" and the "sign_in" function calls the "sign_in" API as well, each one opens up its own modal using the names we gave them earlier on, accordingly also.

Head back to the sign-up form and click on the "submit" button to bring up its widget properties on the right pane. Navigate to the "onClick" option and from the list of options under it choose "Execute a JS Function", choose the "sign_up" function from the subsequent drop downs displayed.

Click on the sign-in tab and on the submit button for the sign-in form there, choose to "Execute a JS Function" as well, but this time select the "sign_in" function for the sign_in button instead.

Adding a protected page

One last thing we must do before we test this, is to add a new page which we will redirect the user to after a successful login, this is in effect the "protected" page that requires successful authentication before it can be accessed.

Head over to the "pages" section and click the plus icon to create a new page, and rename it to "App". Since we have already added that to the onMessageReceived handler on the iframe earlier on.

On this new page, you can create anything you want, since the dashboard isn't the focus of this tutorial. I made a simple dashboard UI (supposedly), thats shown below:

We also want to make sure that we hide the page by default so that when we deploy the application its not visible unless users are navigated to it from completing authentication.

Testing

Finally lets test the authentication flow. Head back to the sign-up form and create a new user.

Once we press the sign-up button, the 2FA modal shows up and shows us the TypingDNA biometrics test

Here, the user will be prompted to type his login credentials again. Still, this time not to validate the details that the backend server had already done, and the two-factor modal wouldn't even show up if any of the login credentials were incorrect.

This time, the user types their credentials for TypingDNA to record and save their typing pattern. We're using the "SameText" pattern matching, which observes a typing pattern for a specific text, the user's login credentials, not just any text. The user could even make mistakes while typing these, and it won't matter because TypingDNA is only observing the user's typing pattern at this point.

So we will type in our login credentials into this form as well and submit it.

After our first submission, we get a prompt telling us that TypingDNA needs to observe our pattern some more, to properly identify the user's typing pattern. This is because the user has just signed up, as such TypingDNA can tell using the user's typing id that this user's typing pattern hasn't been recorded yet, and it tries to record and save it by asking the user to fill the form a couple of times.

According to the TypingDNA documentation, first time pattern recording can require up to 3 or 4 additonal submissions asides the first one. We want to also make sure to type as naturally as possible to avoid having to fill the typing biometrics form for longer.

Eventually, on the third or fourth round we get the prompt letting us know that TypingDNA has recorded and verified the user's typing pattern. Click the "Ok" on the alert and it will redirect you to the application.

Let us also try to sign-in to the application from the sign-in tab, using the details of the user we just created, and see how TypingDNA responds.

The prompt shows up once again, however this time the test immediately recognizes the user's typing pattern since it has recorded it by observing the user's typing pattern over multiple submissions.

Conclusion

This has been quite the run. In this article, we have covered some details about what two-factor authentication is and a brief overview of TypingDNA. We then built a simple authentication flow using Flask and TypingDNA to add an extra layer of protection to a sample Appsmith application. The example used in this article is a relatively simple one, and this model could be adapted to whatever kind of application you plan to build using Appsmith in the future; whether they be slightly more sophisticated than this or even much more complex, you can be sure that you can make it work using the things you've learned from this tutorial.

The code for this application can be found on my GitHub
here

Building An Inventory Tool Using Appsmith and HarperDB

Curious Paul — Mon, 24 Jan 2022 20:34:03 +0000

In this article, I'll show you how to create an inventory tracking tool that helps small businesses sign up on a platform to view and manage products in their inventory.

This article covers how to build such a tool using a popular serverless database called HarperDB and Appsmith.

Setting Up A HarperDB Database
Building The Management Tool Using Appsmith
Conclusion

HarperDB is a flexible, NoSQL serverless solution for hosting data without having to worry about setting up or configuring your backend architecture to host data, as with traditional applications. This allows developers to focus more on building application logic with little to no involvement in database hassles - HarperDB does all that work for you.

Setting Up A HarperDB Database

You'll need to have a HarperDB account; if you don't have one, you can quickly sign up in a few minutes via this link. HarperDB offers three main ways to access the service, namely:

HaperDB Studio: It is a web-based graphical user interface that allows users to create and manage HarperDB instances right from the interface. It also has several tools and features to aid the management process. You can find more info about this feature here.
HarperDB Local Instance: this option allows users to install HarperDB locally on their computers. There are options to install HaperDB using docker, WSL, on windows, or even on Linux OS. To find out more about this, click here.
HarperDB Cloud: the cloud option allows you to access and use HarperDB from your application remotely without having a server running locally on your machine. Using this option, you can create a database instance online and use an API to communicate with the database. To find out more about this option, you can check here.

In this article, I'll be using the HarperDB cloud option, so sign in to your harperDB account, and once logged in, use the Create A New Organization button to create a new "organization" to host database instances; fill in the details as shown below:

Of course, you can name the fields however you want. Then, click the "Create Organisation" button to create an organization. Now you should see your newly created organization show up on your dashboard as shown below:

Click on this new organization, and it should prompt you to create a new HarperDB instance; click on the new button that shows up, and you should be initiated with two options to create an instance.

Choose the "Cloud Instance" option, and it will further ask you to fill in some details about the new database instance to be created, as shown below:

Fill in the details accordingly, as I have done in the image above. Pick a name for your database, and add "access-credentials" to it in terms of a username and a password. You want to make sure to keep these safe and secure; we'll be needing it later on.

Once you have filled in these details accordingly, click on the instance details button to move to the next stage. This would bring up a new form, with options to pick from regarding the pricing plans that HarperDB offers. For demonstration in this article, we only need the free tier plan that provides us with decent good storage space and memory usage, as you can see in the image shown below:

Leave all other settings as they are, and click on the Confirm Insurance Details button to complete the setup. It'll ask you to confirm the details from the previous steps up to the last step, as it shows you an overview of all the options that you have chosen. Click on the button to agree to the terms and submit the form.
You should now see that it has begun creating your database instance on its cloud system.
You should now see that it has begun the process to create your database instance on their cloud system.

This should take a few seconds to complete; if you don't see any change soon enough, refresh the page and once it's done, click on it to add some tables to it. This should take you to a new page, like the one shown below:

On the left side of this page, you can find a field to create a new schema, which would hold our tables. We can add a new schema called "InventoryDB" to have the tables needed for our building inventory tool.

Click on the green checkmark to create the new schema, and it should now show some additional options to add Tables to the database. Let's add a new table called "Products" to hold the details of each product in the inventory.

In the hash_attribute field, I have specified that the hash attribute is called "product_id." The hash attribute is analogous to "Primary Keys" in relational databases and is a unique identifier for every entry in the Products table we just created.
Again click the green checkmark to complete the process to add a new table. The right pane should update and now show a "no record" message, indicating that we haven't added any data to the new table.

Adding Data To The Table

ITo add some data to the database, we can do so in several ways that HarperDB provides, but I will be using a CSV file to add some data to the database. You can download the file from here. Once you have downloaded the file, click on the file icon to the right of the empty pane as shown below:

This would prompt you to enter the location of the CSV file via a URL or choose it from your local storage. Pick the option to upload the file from local storage, and select the CSV file you just downloaded. Once you select the CSV file, it will automatically detect the number of entries and prompt you to accept the new changes.

Click the insert records button to confirm the upload. Once it's done processing, it should add a couple of entries into the Products table as shown below:

Building The Management Tool Using Appsmith

To begin with you want to make sure you've signed up on Appsmith, its super-easy you can sign up here. Once you have that login to your dashboard and create a new application, this should bring you to the development environment like the one shown below:

We'll start by clicking and dragging a table widget unto the correct area; this table will display a business's product listings and the details of each one:

You can resize the table by dragging on the edges; however, leave some space to add one more widget - a form. This form will collect information for a new product to be added to the list and serve as a means of editing already existing products in the catalog.

Click and drag the form widget onto the right area so that it fits the right of the table as shown below; you may need to do some resizing to get it to work in there.

Populating The Table

To populate the table with data from our database, we'll be using the HarperDB API, which can be accessed via the cloud instance URL, and you can find that in the config section of the cloud instance dashboard.

You'll need the instance URL, as well as the Instance API Auth header; you can click on the copy icon beside each one to copy them when required. Next, head over to the appsmith dashboard and click on the Datasources option to create a new API.

It should prompt you to enter details about your API on a new page; these include a name for the API (I called mine "FetchProducts"), the URL, headers, and data or request body to be sent to the API. Fill in the details as shown below:

Paste the HarperDB Instance URL into the URL field of the appsmith API tool, as shown above.
For the value of Authorization in the headers, It's usually of the format: Basic <Instance API Auth key>.

Next, we must write a query as part of the request body to fetch all the products from the Products table in our database using SQL query. This is a feature that HarperDB offers its users; even though the database system isn't a relational database, HarperDB can read SQL queries and interact with them as though it were a relational database.

{
    "operation": "sql",
    "sql": "SELECT product_id, name, description, price, quantity, backorderLimit, backordered FROM InventoryDB.Products"
}

Here I specify the operation type to be an "SQL" query and then wrote the SQL to query for all data in the Products table found under our InventoryDB schema that we created earlier. This is what would be in the body of the request that we will send to the HarperDB API, as you can see below:

Also, please observe that the request type is POST and not GET, even though what we're doing is retrieving data.
Now head back to the table widget, and we'll ask the table to fetch data from this API instead of the hard-coded data in it. Click on the table widget, and its context manager should pop up right beside it, and under the field that reads - Table Data, you want to clear out the hard-coded data in it and add the following instead:

{{FetchProducts.data}}

This will populate the table with results from the api instead.

We also want to set the Column Type on the price, backorderLimit, and quantity columns to a type of Number so that Appsmith can adequately handle the data. Appsmith allows us the flexibility of editing columns too; so click on the settings icon on any column you wish to edit and change the settings accordingly.

So click on the icon, and change the Column Type from the list of options displayed to Number, as shown below:

Building The Inventory Form

To create a form, we'll need the Text and Input widgets which will help us to name and create the input fields for the form. For this form, we need fields that correspond to the title of each column, except, of course, the product_id column. So drag and drop the widget and position them so that the form looks like the one shown below:

Observe that for the back ordered column, we drag a Switch widget to the form as opposed to an input widget because its values are boolean, and that corresponds to a switch or a checkbox widget which can represent both states as checked or unchecked.

Now we want to be able to prefill these fields when any product is selected on the table to edit them on the form. To do this, we leverage the Default value property of the input widget and add "moustache" syntax to fetch data on the selected row and add it to the field.

Add the following to the Default value entry on the Product name field to prefill it with the product's name on a selected row.

{{Table1.selectedRow.name}}

If you don't see the details of the input widget, click on the settings icon beside it to bring up the properties of the widget, as shown below:

Do this for the other fields adding in the corresponding column name for each one. Also, set the Data type property for the input fields: quantity, backorderLimit, and price to the Number type.

For the "backordered" switch use the Default Selected option to add the moustache syntax as with the other fields, as shown below; this will automatically change the state of the switch depending on what value on the "backordered" column is for the selected row.

Updating A Product

Now let us write a query that helps update the document in the database when we change something in the form and hit the submit button. This query will be tethered to the Submit button widget automatically added when the form is created.

We will now create a new API to handle this, using the same steps as we have done for the first one, give this a name (UpdateProduct), and use the same headers from before. In the body of the request, we want to add the following to pick data from the input fields and send them to the API:

{
    "operation": "update",
    "schema": "InventoryDB",
    "table": "Products",
    "records": [
        {
            "product_id": {{Table1.selectedRow.product_id}},
            "name": {{Input1.text}},
            "description": {{Input2.text}},
            "price": {{Input3.text}},                        
            "quantity": {{Input4.text}},
            "backorderLimit": {{Input5.text}},
            "backordered": {{Switch1.isSwitchedOn}}
        }
    ]
}

This query uses a NoSQL query format to update records in the database, which proves just how flexible HarperDB is. In the query, we fetch the ID of the currently selected row and use the data from the prefilled and or edited form to update the details of the product on the HarperDB database.
Let's now tie this with the submit button so that when we edit the form and click submit, this calls the API. Head over to the "submit" widget and bring up the settings pane, and under the Actions section, choose the option to Execute a query and then select the UpdateProduct API from the list of options shown.

We also want the table to refresh its data "onSuccess" of the API query. We do this by specifying an onSuccess action right beneath the onClick action of the "submit" button. This also executes a query via the HarperDB API, which we created first - remember, this API is responsible for populating the table with data from the database. You can now select any row from the table, edit it in the form and send the request to update the database, which updates the table accordingly.

Conclusion

In this article, we have seen a brief introduction to HarperDB and the kind of flexibility it offers; we created a HarperDB database, added a new schema, created a new table, and prefilled it with data from a CSV file, thanks to the option provided by the HarperDB dashboard.
We also got access to the HarperDB API for our cloud instance, which helped us interact with Appsmith later. Lastly, we worked with Appsmith to build a simple product management tool for business owners and connected it to our database API, thanks to the datasources option provided by Appsmith also, which made the integration smooth and easy.

Hopefully, this tutorial has further shown you what is possible with serverless technologies like Appsmith and HarperDB. Thanks for sticking with me till the end; happy coding!

Making The Earth Greener With Project Gaia

Curious Paul — Thu, 13 Jan 2022 22:53:49 +0000

Overview

The Gaia project aims to help in the fight against global warming and deteriorating climate conditions; to help make the world "greener" and safer, by making it easier to engage "green" projects and foster growth for every project.

The platform aggregates a list of projects directly involved with making a Earth "greener", and allows users to donate to the cause of a project that they find interesting or believe in.

NGOs and other organisations with "green" projects can apply to create an account on Gaia, and raise the funding that they need to complete their project(s) in due time. This way we can help raise awareness about climate change, and make it easier for the average individual to be involved.

How We Built Gaia

We wanted Gaia to be user friendly, and easily accessible so some design considerations had to be taken into account from the beginning, before we even started writing code.

Once we had a user-interface we all agreed with, work commenced on the frontend interface for which the ReactJs web framwork was used.

The backend was written in python using the Flask web framework.

User data, and projects' information were stored on a serverless instance via MongoDB atlas. We employed the use of MongoDB's very famous python client library (with its rich documentation) - "PyMongo" to interact with the serverless instance of the MongoDB database. For example, with PyMongo, we could "seed" data into the database instance as follows:

projects = []
for card in cards_:
    project_url = requests.get(card.find('h3').find('a')['href']).text
    project_page = BeautifulSoup(project_url, 'html.parser')
    try:
        obj_ = {
            '_id':str(uuid.uuid4()),
            'project_headline': project_page.find('main').find('p').string,
            'paypal_value': card.find('form').find('input', attrs={'name': 'hosted_button_id'})['value'],
            "project_url": card.find('h3').find('a')['href'],
            "name": card.find('h3').find('a').string,
            "image_url": card.find('img')['src'],
            "paypal_url": card.find('form').get_attribute_list('action')[0]
        }
        db.project.insert_one(obj_)
        projects.append(obj_)
    except Exception:
        print(card, end="Has issue!")

Submission Category:

"Custom Adventure"

Link to Code

UI (Figma): https://www.figma.com/file/iBKIwWJ7O4NObpr5vNo4Rj/Project-Gaia
Backend: https://github.com/Curiouspaul1/Gaia
Frontend: https://github.com/Iamsheye/gaia

Screenshots/demo

Live URL: https://project-gaia.vercel.app

Collaborators

Building A Meme Generator using Appsmith

Curious Paul — Sun, 31 Oct 2021 17:43:52 +0000

In this article I will be showing you how to build a simple meme generator platform using appsmith and a third party api called Humor Api

Pre-Requisites

In order to follow along with this tutorial you will need the following:

Appsmith account: if you don't already have one you can create one via this link

Building The Interface on Appsmith

We'll start by building the interface to the meme generator platform on appsmith, so login to your appsmith dashboard and click on the button to create a new application.

On the design area, we're going to drag an image widget to the middle of the screen which will display the meme, we also need a button widget that will randomize the meme each time its clicked, change the default text on the button to generate meme.

Your design should look something like that shown below:

Integrating With HumorApi

To begin with you need to sign up for a free account on HumorApi platform and then get your api-key which will be used to communicate with the Humor APi server. You can sign up for a free account . Once you're signed up head over to the Profile section on your dashboard and copy your api-key as shown below:

We will now link the interface with the api, in order for us to this we need to create a new data source. Head over to the Datasources section on the dashboard and then click the option to create a new api, give this api a name, perhaps randomMemes. It will send a GET request to the Humor Api endpoint of https://api.humorapi.com/memes/random?api-key=YOUR-API-KEY&keywords=random.

This API will be responsible for fetching random memes from the public api. Save this api and head back to the widgets section. Head over to the submit widget and bring up the settings pane, and under the Actions section choose the option to Execute a query and then select the randomMemes api from the list of options showed.

On the image widget bring up the settings pane as well, and in the image option add the following so that the image loads the url from the response of the random meme api.

{{randomMemes.data.url}}

Now click on the generate meme button and you should now see that the image changes the meme appearing on it, each time you click it.

We can choose to deploy this application and share with the public however we want. That's it, you have successfully created a random meme generator in a few easy steps, thanks for staying with me - have fun coding!.

Building Internal Tools Using Appsmith, Flask And Heroku

Curious Paul — Sat, 30 Oct 2021 15:52:26 +0000

In this article I will be showing you how to build a simple inventory management tool using Appsmith and Flask, which will serve data to the Appsmith environmennt. You will see how to build and configure a simple backend api using flask as well as how to properly integrate your Appsmith application with the backend api.

Pre-Requisites

In order to follow along with this tutorial, you will need to have the following setup:

Python3: You wiill need this in order to run the dependencies for the project (including Flask), I am also assuming that you are familiar with python3 and already know how to build simple flask applications.
Appsmith Account: You will also need an Appsmith account in order to build the interface to our tool. If you don't already have one, you can sign up for one via this link.
Git and a Github Acount

Building And Deploying A Flask API

We'll start by creating a new folder to host our backend application, you can call this whatever you want - mine is called core. Navigate to this folder from the terminal and create a new file called server.py, add another file called Procfile after doing this your project folder should look like the following:

core/
|__server.py
|__Procfile

While we're in this folder from the terminal, let's create a new virtual environment using the python package virtualenv

virtualenv server

Once this is done, activate the virtual environment as follows:

source server/bin/activate

or if you're on windows:

.\server\scripts\activate

Once you do this you should see your current file path on the terminal prefixed with the name of the virtual environment in parentheses.

Now using the pip command install Flask and Flask-Sqlalchemy,gunicorn, Flask-CORS and Flask-Marhsmallow as shown below:

pip install flask flask-sqlalchemy flask-cors gunicorn flask-marshmallow marshmallow-sqlalchemy

Once they're installed we can start writing our flask server, so open the server.py file and add the following lines of code:

from flask import Flask, request, jsonify
from flask_sqlalchemy import SQLAlchemy
from flask_marshmallow import Marshmallow
from flask_cors import CORS
import os

basedir = os.path.abspath(os.getcwd())

# instantiate new flask app
app = Flask(__name__)

# app config for database
app.config['SQLALCHEMY_DATABASE_URI'] = f"sqlite:///{basedir}/demo.db"
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
CORS(app)

# database models
db = SQLAlchemy(app)
ma = Marshmallow(app)


class Product(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))
    price = db.Column(db.Float)
    description = db.Column(db.Text)
    quantity = db.Column(db.Integer)


class ProductSchema(ma.SQLAlchemyAutoSchema):
    class Meta:
        model = Product
        load_instance = True
products_schema = ProductSchema(many=True)

@app.route('/get_products')
def fetch_products():
    all_ = Product.query.all()
    return jsonify(products_schema.dump(all_)), 200

@app.route('/add_product', methods=['POST'])
def add_note():
    data = request.get_json(force=True)
    new_product = Product(
        name=data['name'],
        price=data['price'],
        description=data['description'],
        quantity=data['quantity']
    )
    try:
        db.session.add(new_product)
        db.session.commit()
        return {
            "status": "Success"
        }, 200
    except Exception as e:
        print(e)
        return {
            "status": "Error"
        }, 500

@app.route('/edit_product', methods=['PUT'])
def edit_note():
    data = request.get_json(force=True)
    # find product
    product = Product.query.filter_by(id=data['id']).first()
    for key, value in data.items():
        setattr(product, key, value)
    try:
        db.session.commit()
        return {
            "status": "Success"
        }, 200
    except Exception:
        return {
            "status": "Error"
        }, 500


@app.route('/delete_product', methods=['DELETE'])
def delete_note():
    data = request.get_json(force=True)
    # find product
    product = Product.query.filter_by(id=data['id']).first()
    db.session.delete(product)
    try:
        db.session.commit()
        return {
            "status": "Success"
        }, 200
    except Exception:
        return {
            "status": "Error"
        }, 500


if __name__=="__main__":
    db.create_all()
    app.run(debug=True)

In the server file, we import the required dependencies, create a new flask app instance, add some necessary configurations including "cors" and database config, and specified three endpoints to which we can send requests.

Save this file and run the script from the terminal using the following command:

python server.py

You should see the server start running with logs similar to these :

Deploying To Heroku

This is great but in order for our server to be publicly accessible we must deploy it to a cloud service provider, and for that we would be using Heroku.

Heroku is a PaaS cloud service provider that helps us to deploy application really easily without having to worry about the kind of machine to provision for the software and how to scale them - Heroku does all that on our behalf, all we have to do is tell them howto run our application, and we do that using the Procfile that we created earlier on.

For this you will need to have an account with Heroku, you can easily create one from this link. You will also need to download the heroku cli from here.

Once you have the cli tool installed, open up a new terminal and navigate to the project directory, and login using the command:

heroku login

This would prompt you to open your browser and log you in from there, by the time its done you should be logged in from the terminal as well, you can now create a new heroku app as follows:

heroku create appsmith-server

I called mine appsmith-server, you can give yours any name as well. Since Heroku doesn't allow shared names you might have to come up with a much cooler name.

Now that our heroku application has been created, let's tell heroku what to run in the Procfile, so open the Procfile and add the following to it:

web: python gunicorn:app

The Procfile deployment specification follows the format of

[process_type]: [command]

Likewise, I have specified that the "process_type" be of type "web", meaning the application to be deployed is a web application. The "command" to run the application has also been specified (its supposed to run the flask server using gunicorn). What this means is that when Heroku wants to spin up an instance of our application it looks at the Procfile and uses the instructions there to run the application.

Before we finally deploy we need to tell Heroku, of the things it needs to install before running the application, and this is done using the requirements.txt file
which Heroku will automatically look for during deloyment. We can easily append the requirements from our virtual environment using pip as follows:

pip freeze>requirements.txt

This wll automatically take all the installed dependencies and add them to a file called requirements.txt, so you should find that it created a new file for you by that name that has the following contents, or at least similar contents:

click==8.0.3
colorama==0.4.4
Flask==2.0.2
Flask-Cors==3.0.10
Flask-SQLAlchemy==2.5.1
greenlet==1.1.2
itsdangerous==2.0.1
Jinja2==3.0.2
MarkupSafe==2.0.1
six==1.16.0
SQLAlchemy==1.4.26
Werkzeug==2.0.2

To deploy the application, we'll be using git, so head back to the terminal ad initialize a git repository in the project folder using the init command, and then add and commit the changes to version control history.

Now we will add a remote origin for the heroku application, so that we can push and in effect deploy the application from the terminal using git.

heroku git:remote -a <Your-heroku-app-name>

This will create a private repository on heroku that your updates will be pushed to when you push to heroku. Now we can finally deploy our application by pushing the committed code as follows:

git push heroku main

This would begin the deployment opertaion with logs similar to these:

We see that the request goes through, and this is sign that the server is up and running and is accessible publicly. Let's head over to appsmith and build the interface for this tool.

Building The Management Tool Using Appsmith

To begin with you want to login to your Appsmith dashboard and create a new application, this should bring you to the development environment like the one shown below:

This environment is where we'd be building our "application" and its mostly a drag and drop environment with widgets and other build tools on the left pane and the wider space to the right is the development area where you drag widgets on.

We'll start by clicking and dragging a table widget unto the right area, this table will display a business's product inventory, and the details of each one:

Resize the table by dragging on the edges, however leave some space so that we can add one more widget - a form. This form will collect information for a new product to be added to the list and will also serve as a means of editing already existing products in the catalogue.

Click and drag the form widget onto the right area so that it fits to the right of the table as shown below, you may need to do some resizing to get it to fit in there:

Building The Form

To create a form, we'll need the Text and Input widgets which will help us to name and create the input fields for the form. For this form we need fields that will hold details of each product including the name, description, price, and quantity. So drag text labels and input widgets for each field, as shown below:

Also rename the buttons on the form to be Add new and Update, as they will serve to create new products and update existing ones

Fetching Data From The API

Let's try to create a new product using the form we created earlier on. So head back to the appsmith dashbord and under the Datasources section click on the create new API option to add a new API to communicate with from your appsmnith application

It should prompt you to enter details about your api on a new page, these includes a name for the API (I called mine "AddProduct"), the URL, headers and data or request body to be sent to the Api. Fill the details as shown below:

Here we have added the url to our heroku deployment and added the endpoint add_product that sends a POST request to add a new product to the database. In the body add the following to create a payload that contains data from the form.

{
  "name": {{Input1.text}},
    "price": {{Input2.text}},
    "description": {{Input3.text}},
    "quantity": {{Input4.text}}
}

Add A New Product

Let's now tie this with the Add new button so that when we edit the form and click Add new the this api is called. Head over to the Add new widget and bring up the settings pane, and under the Actions section choose the onClick option, and choose the option to Execute a query and then select the AddProduct api from the list of options showed.

Next to this onClick action is the onSuccess option, and this will trigger on success of the request sent when the button is clicked. We want the table to be updated when we add a new product from the form, so we will create a new api to fill the table with data from the database, and then call that api whenever we add a new product from the form as the onSuccess action.

What this will do is to refresh the table each time we add a new product to the database. So head over to the datasources and create a new API called getProducts that sends a GET request to the server endpoint of get_products as shown below:

Head back to the onSuccess action of the Add new button from earlier and choose the option to Execute a query and then select the getProducts api from the list of options showed.

Now head to the table widget and we'll ask the table to fetch data from this api instead of the hard-coded data in it. Click on the table widget and its context manager should pop-up right beside it, and under the field that reads - Table Data, you want to clear out the hard-coded data in it and add the following instead:

{{getProducts.data}}

You should see the data show up on the table, we can now add a new product from the form and then when we click the Add new button on the form the new data should create a new row in the table.

Edit A Product

We also want to be able to prefill the form fields when any product is selected on the table so that we can edit them on the form. To do this we leverage on the Default value property of the input widget and add moustache syntax to fetch data on the selected row and add it to the field.

Add the following to the Default value entry on the Name field to prefill it with the name of the product on a selected row.

{{Table1.selectedRow.name}}

If you don't see the details of the input widget, click on the settings icon beside it to bring up the properties of the widegt, as shown below

Do this for the other fields adding in the corresponding column name for each one. Also set the Data type property for the input fields: quantity, and price to type of Number. This way we can edit any product by clicking on it making the changes in the form and then use the Update button on the form to submit the edit to the database.

Let's create a new API to handle the product update, so as before create a new api and name it updateProduct, that sends a PUT request to the server on the /edit_product endpoint. Add the following to the body of the request:

{
    "id": {{Table1.selectedRow.id}},
    "name": {{Input1.text}},
    "price": {{Input2.text}},
    "description": {{Input3.text}},
    "quantity": {{Input4.text}}
}

Now link this to the update button just like we did for the Add new button as an onClick action, also specify the getProducts api as an onSuccess action so that the table reloads the data. Now we can click on any row and edit a product from the form and it'll be automatically updated on the table.

Delete A Product

In order to delete a product we can add a third button widget to the form, create a deleteProduct api that sends a DELETE request to the server on the /delete_product endpoint, with a payload defined as follows:

{
    "id": {{Table1.selectedRow.id}}
}

Tie this to the new delete button and add an onSuccess action to call the getProducts api once again like before.

Conclusion

We have come quite a long way, now haven't we?. In this article, we have seen how to build and deploy a server using flask and heroku, we worked with Appsmith to build a simple product inventory management tool for business owners, and connected it to our API. There's more that we could possibly accomplish using Appsmith and a traditional web server, for example we could embed the appsmith tool we built directly on a web page and serve the web page on our flask server.
That is just one of the many possibilities with Appsmith and I'm hoping this article has further shown you what is possible with serverless technologies like Appsmith.

Thanks for sticking with me till the end, happy coding!.

Building A Product Management Tool Using Appsmith and FaunaDB

Curious Paul — Sun, 24 Oct 2021 23:24:13 +0000

In this article, I'll be showing you how to create a product management tool that helps, small business signed up on a mythical e-commerce platform manage products in their catalogue. This tool will allow users to view products and edit them from their catalogues. This article will also help to show how you can integrate Appsmith with other serverless tools like FaunaDB.

Setting Up A FaunaDB Database
Building The Management Tool Using Appsmith
Conclusion

Fauna is a flexible, developer-friendly, NoSQL database delivered as a secure and scalable cloud API with native GraphQL. It is a serverless solution for hosting data without having to worry about setting up or configuring your backend architecture to host data, as with traditional applications. This allows developers to focus more on building application logic with little to no involvement in database hassles - Fauna handles all that for you.

Setting Up A FaunaDB Database

In order to follow along, you'll need to have a FaunaDB account, if you don't have one you can easily sign up in a few minutes via this link.

Once you're signed up, log in to your Fauna dashboard and use the Create Database button to create a new database, fill in the details as shown below:

Observe the Use demo data option and see that it is checked, this will tell Fauna to help us prepopulate this new database with demo data that we can use to play around, and co-incidentally (or not), this data is related to customers and businesses. Fauna will add collections, documents as well as indexes, and you can find them in the correspoding sections of your database dashboard as shown below:

Generating An API Key

Now that this is done, what we need now is an Api key, which will allow us communicate with our database from other applications, like our appsmith tool for instance. To get this head over to the Security tab of the database dashboard and click on the New key option to generate a new key, you can give the key a name if you want, leave the other options as they are and click the Save button to generate a new key.

Once you get the key, you need to copy it and save it somewhere for later when we need it. That's it for setting up the database, prettu easy as you can see, now lets create the interface for our tool.

Building The Management Tool Using Appsmith

To begin with you want to make sure you've signed up with Appsmith, its super-easy you can sign up here. Once you have that login to your dashboard and create a new application, this should bring you to the development environment like the one shown below:

We'll start by clicking and dragging a table widget unto the right area, this table will display a business's product listings, and the details of each one:

You can resize the table by dragging on the edges, however leave some space so that we can add one more widget - a form. This form will collect information for a new product to be added to the list and will also serve as a means of editing already existing products in the catalogue.

Click and drag the form widget onto the right area so that it fits to the right of the table as shown below, you may need to do some resizing to get it to fit in there:

Populating The Table

In order to populate the table with data from our database, we'll be using the GraphQL api that Fauna automatically created for us when we created the database - again this is courtesy of the option we checked earlier on when we created the database to allow Fauna pre-populate the database with data on our behalf.

In order to see what queries we can run head over to the GraphQL section in the database dashboard to view the queries Fauna created on our behalf:

The link to this graphql api is in the searchbox on this page, copy it and head over to the appsmith dashboard from before, and click on the Datasources option to create a new api.

It should prompt you to enter details about your api on a new page, these includes a name for the API (I called mine FaunaApi), the URL, headers and data or request body to be sent to the Api. Fill the details as shown below:

For the value of Authorization in the headers, its usually in the format of Bearer [Fauna Secret] which is what we got from previous steps, copy that and paste it in, as I have done.

Next we must now write the query that fetches data from our api, so in the body of the request select type JSON and add the following piece of query to fetch all products on our hypothetical platform:

{{
    JSON.stringify(
        {
            variable: null,
            query: `
                {
                    allProducts{
                        data{
                            _id
                            name
                            description
                            price
                            backordered
                            backorderLimit
                            quantity
                            store{
                                name
                            }
                        }
                    }
                }
            `
        }
    )
}}

Observe that we use the JSON.stringify method provided by appsmith (via the moustache syntax) to ignore the line breaks. Inside the query we have the query name - allProducts and is one specified by Fauna on our behalf you can check its doc back at the Fauna dashboard under the GraphQL section to see available queries and mutations.

Now head back to the table widget and we'll ask the table to fetch data from this api instead of the hard-coded data in it. Click on the table widget and its context manager should pop-up right beside it, and under the field that reads - Table Data, you want to clear out the hard-coded data in it and add the following instead:

{{FaunaApi.data.data.allProducts.data}}

This will populate the table with results from the api instead.

The store column seems to come as an object, as opposed to a simple string. This is because stores are independent documents in the database too, and have other attributes as well, however in this query we only fetch their name but the result comes in an object format regardless.

Appsmith allows us the flexibility of editing columns too, so we can click on the settings icon on the store column in the Columns section and in the computed value option from the menu that shows up, we change the value to

{{currentRow.store.name}}

We also want to set the Column Type on the price, backorderLimit and quantity columns to a type of Number so that Appsmith can properly handle the data.

Building The Form

To create a form, we'll need the Text and Input widgets which will help us to name and create the input fields for the form. For this form we need fields that correspond to the title of each column except of course the _id and store column, those should be immutable ideally.

So drag and drop the widget and position them so that the form looks like the one shown below:

Observe that for the backordered column, we drag a Switch widget to the form as opposed to an input widget because it's values are boolean and that corresponds to a switch or a checkbox widget which can represent both states as checked or unchecked.

Now we want to be able to prefill these fields when any product is selected on the table so that we can edit them on the form. To do this we leverage on the Default value property of the input widget and add moustache syntax to fetch data on the selected row and add it to the field.

Add the following to the Default value entry on the Product name field to prefill it with the name of the product on a selected row.

{{Table1.selectedRow.name}}

If you don't see the details of the input widget, click on the settings icon beside it to bring up the properties of the widegt, as shown below:

Do this for the other fields adding in the corresponding column name for each one. Also set the Data type property for the input fields: quantity, backorderLimit, and price to type of Number.

For the "backordered" switch use the Default Selected option to add the moustache syntax as with the other fields, as shown below, this will automatically change the state of the switch depending on what value on the "backordered" column is for the selected row.

Updating A Product

Once this is done, we need to write a query that helps to update the document in the database when we change something in the form and hit the submit button. This query will be tethered to the Submit button widget, which was automatically added when the form was created.

We will now create a new Api to handle this, using the same steps as we have done for the first one, give this a name, and use the same headers from before. In the body of the request, we want to add the following to pick data from the input fields and send them to the graphQL api:

{{
    JSON.stringify(
    {
        query: `mutation ($object: ProductInput!){
                            updateProduct(
                                id: "${Table1.selectedRow._id}",
                                data: $object
                            )
                            {
                                name
                            }
                        }`,
        variables: {
            "object": {
                    name: Input1.text,
                    description: Input2.text,
                    price: Input3.text,                        
                    quantity: Input4.text,
                    backorderLimit: Input6.text,
                    backordered: Switch1.isSwitchedOn
                }
        }
    }
)}}

This query fetches the ID of the currently selected row, and uses the data from the pre-filled and or edited form to update the details of the produt on the Fauna database.

Let's now tie this with the submit button so that when we edit the form and click submit the this api is called. Head over to the submit widget and bring up the settings pane, and under the Actions section choose the option to Execute a query and then select the updateProduct api from the list of options showed.

We also want the table to refresh its data onSuccess of the api query, and we do this by specifying an onSuccess action right beneath the onClick action of the submit button, this also Executes a query via the FaunaApi which we created first - remember this api is responsible for populating the table with data from the database. You can now select any row from the table, edit it in the form and send the request to update the database, which in turn updates the table accordingly.

Conclusion

In this article, we have seen a brief introduction to Fauna, and the kind of flexibility it offers, we created a FaunaDB database, and generated data automatically with the help of Fauna including a full fledged GraphQL API, which helped us to intereact with Appsmith later on, lastly we worked with Appsmith to build a simple product management tool for business owners, and connected it to our Fauna API, using datasources from Appsmith. Hopefully this tutorial has further shown you what is possible with serverless technologies like Appsmith and Fauna. Thanks for sticking with me till the end, happy coding!.

How to Create Simple Versioning In your Database Using Fauna's Temporality Feature

Curious Paul — Wed, 22 Sep 2021 22:28:32 +0000

What is temporality ?

The temporality feature in Fauna is a feature that allows users to see how the data in their database has changed over time. The temporality feature involves two unique and interesting functions:

The At function
The Events function

In this article, I’ll be showing you how to use the temporality features provided by Fauna to create a simple “versioning” tool that can help you manage different versions of your data across their lifetime in the database — don’t worry it’ll make sense as you proceed.

Creating and configuring the database

The first thing you must do is to create a Fauna database instance and add some data to it. To do this head over to your Fauna dashboard and click on the create database button on the dashboard.

This brings up a prompt where you can type in a name for your database, and add other config options. Add a name for the database and make sure to check the “use demo data” option so Fauna can pre-populate the database with dummy data, as well as indexes that you can use for test purposes.

Fetching an API key

Next you’ll head over to the Security tab and select the new key option to generate a new API key, so you can communicate with Fauna securely from your application. Clicking on the “new key” option should prompt you to enter details about this new key, most of which have already been pre-filled.

The default options are just good for the purposes of this tutorial, so you can leave them as they are and click “save” to generate the key.

Copy the key you get and save it in a secure location. I’ll be saving mine in an environment variable called “Fauna-secret” and I’ll be using it for the rest of this article, to reference the key.

Building the “versioning” middle-ware

Pre-Requisites

For the purposes of this tutorial you will be needing the following :

Python3
Faunadb python package: this can be installed from the command line or terminal using pip as follows:

pip install faunadb

The “At” Command

The first temporality tool that Fauna offers is the At command, which takes in a timestamp and allows you to see the state of a collection at that point in time.

Fauna automatically adds a timestamp upon creation of the database, and as well as when new data is added to a collection. If more than one document is added to a collection at a time, then they’ll share the same timestamp.

We can run a simple query to see all “customers” data from the database and observe the timestamp on each document in the response. To do this create a file called main.py and add the following lines of code to it.

from faunadb.client import FaunaClient
from faunadb.errors import FaunaError, HttpError
from faunadb import query as q
from dotenv import load_dotenv
from typing import Optional
import os

load_dotenv()

client = FaunaClient(secret=os.getenv('Fauna-secret'))

# reviewing customer data
customers = client.query(
    q.map_(
        lambda x: q.get(x),
        q.paginate(
            q.document(q.collection('customers'))
        )
    )
)

print(customers)

The result from this query should look like the image below:

Observe how the documents have the same timestamp in the response, since they were created at the same time. Copy this timestamp so you can use it to see what the “customer” collection was like at this time after we’ve added new data to the collection - by passing it to the At function.

Let’s add some new documents to the “customer” collection and then use the timestamp from before to see what the table looked like at that time.

From your dashboard on Fauna, head over to the “customers” collection and use the New Document option to add two new customer documents, with whatever info you choose.

Do this one more time so you have two new customers. Once this is done, comment out the code in main.py and add the following lines of code to the file in order to see the documents that were in the customer collections at the timestamp you copied earlier.

from faunadb.client import FaunaClient
from faunadb.errors import FaunaError, HttpError
from faunadb import query as q
from dotenv import load_dotenv
from typing import Optional
import os

load_dotenv()

client = FaunaClient(secret=os.getenv('Fauna-secret'))

# # reviewing customer data
# customers = client.query(
#     q.map_(
#         lambda x: q.get(x),
#         q.paginate(
#             q.document(q.collection('customers'))
#         )
#     )
# )

# print(customers)

data = client.query(
    q.at(
        1632242211590000,
        q.paginate(
            q.documents(q.collection('customers'))
        )
    )
)

print(data)

Running this would give us the following result:

This is obviously not the latest version of our customer table, since we’ve added two new documents to it. This is instead a snapshot of what the collection was like at that timestamp. So with the At function we can peek at the data stored in the database at any given point recorded.

The “Event” Command

This is the second temporality feature that Fauna offers, and it allows you to see the different versions of a document over its lifetime in the database. This is possible because Fauna creates a copy each time an update is made to the document, as opposed to re-writing the document itself.

In order to test this, let’s update one of the customer’s data, comment the previous lines of code and add the following to update the user with id of “101”

from faunadb.client import FaunaClient
from faunadb.errors import FaunaError, HttpError
from faunadb import query as q
from dotenv import load_dotenv
from typing import Optional
import os

load_dotenv()

client = FaunaClient(secret=os.getenv('Fauna-secret'))

# # reviewing customer data
# customers = client.query(
#     q.map_(
#         lambda x: q.get(x),
#         q.paginate(
#             q.document(q.collection('customers'))
#         )
#     )
# )

# print(customers)

# data = client.query(
#     q.at(
#         1632242211590000,
#         q.paginate(
#             q.documents(q.collection('customers'))
#         )
#     )
# )

# print(data)

# update name
client.query(
    q.update(
        q.ref(
            q.collection('customers'),
            "101"
        ),
        {'data': {'firstName':'Boyle', 'lastName':'Johnson'}}
    )
)

# update contact details
client.query(
    q.update(
        q.ref(
            q.collection('customers'),
            "101"
        ),
        {'data': {'telephone': '854-456-3982'}}
    )
)

The code above will update the user twice, that way you can see how it’s changed over the course of two updates. Now let’s use the event command to see the versions of this document. Comment out these lines of code as with the previous ones and add the following instead.

from faunadb.client import FaunaClient
from faunadb.errors import FaunaError, HttpError
from faunadb import query as q
from dotenv import load_dotenv
from typing import Optional
import os

load_dotenv()

client = FaunaClient(secret=os.getenv('Fauna-secret'))

# ...
# ..

# update name
# client.query(
#     q.update(
#         q.ref(
#             q.collection('customers'),
#             "101"
#         ),
#         {'data': {'firstName':'Boyle', 'lastName':'Johnson'}}
#     )
# )

# # update contact details
# client.query(
#     q.update(
#         q.ref(
#             q.collection('customers'),
#             "101"
#         ),
#         {'data': {'telephone': '854-456-3982'}}
#     )
# )
results = client.query(
    q.paginate(
        q.events(
            q.ref(
                q.collection('customers'), "101"
            )
        )
    )
)
for resp in results['data']:
    print(resp, end="\n\n")

Running the main.py file this time gives us the following results, containing the different versions of the file and what operation was performed on them each time, as well their corresponding timestamps.

These two functions At and Events are what you’ll be using to create the “versioning” tool.

The versioning tool

Now that you already know what At and Event are, we can begin to build a versioning tool that can help us revert from the current state of our document to a previous state, when we need to. To begin, clear out the code in main.py except of course the imports and the Fauna client instance. We’ll start by writing a function called downgrade that will let us jump backward in time. So add the following lines of code to main.py

from faunadb.client import FaunaClient
from faunadb.errors import FaunaError, HttpError
from faunadb import query as q
from dotenv import load_dotenv
from typing import Optional
import os

load_dotenv()

client = FaunaClient(secret=os.getenv('Fauna-secret'))


def introspect(ref_id: str):
    events_ = client.query(
        q.paginate(
            q.events(
                q.ref(
                    q.collection('customers'), ref_id
                )
            )
        )
    )
    return events_


def downgrade(ref_id: str, steps: Optional[int] = -2):
    events_ = introspect(ref_id)
    # fetch previous state and update document with it instead
    try:
        client.query(
            q.update(
                q.ref(
                    q.collection("customers"), ref_id
                ),
                {
                    'data': events_['data'][steps]['data']
                }
            )
        )
    except FaunaError as e:
        return "An error occurred while trying to update object, try again."
    return "downgraded object successfully"

print(introspect("102")) # inspect the history of the document before running the downgrade
print(downgrade("102"))

Here I’ve added two functions, one of which is called introspect and the other downgrade. The introspect function allows us to inspect the different versions of the document so we can determine which one we want to jump to. The list of items in the introspect function is in ascending order, meaning the latest version of the document is in the last place — which is why in the downgrade function we use negative index to reference it.

Both functions take in the ref_id as an argument, so you need to know the id of the document you want to edit. The downgrade function takes one extra optional parameter however, called steps. This is used to specify which of the versions is to be jumped back to, and it's set to -2 by default meaning it's a step up from the last (or latest version of the document), or the immediate previous version of the document. If you don’t specify a step, it assumes you want that, however if you do then it uses the value you provide instead.

Note: For each downgrade the function creates a new update with the info gotten from the introspect function. So in essence, the history of the document continues to lengthen and so does the latest version. For optimum experience you may want to introspect and pick a specific version then jump there, if it's not the immediate previous version of the latest one.

Conclusion

In this tutorial, I have shown you how to create and pre-populate your database from your Fauna dashboard. I have also explained in detail the temporality features provided by Fauna, and further went on to show you how you might build a simple versioning script that could help improve your experience working with Fauna. The workings of the temporality features are not bounded by what I covered in this article, there’s a lot more you could accomplish by using these features, you could possibly even want to extend my implementation by building a class instead and adding more features to help your development process.

You can find the code on github via this link:

https://github.com/Curiouspaul1/fauna-temporality-demo

Written in connection with the Write with Fauna Program.

Building An E-commerce Telegram Bot Using Python and Fauna.

Curious Paul — Sun, 13 Jun 2021 00:18:14 +0000

This article will show you how to build a telegram bot for a small-scale business owner. This bot will be pretty similar to the popular platform WhatsApp Business in terms of its features. We will see how to implement those features and set up our database on Fauna’s serverless system to host user data.

Before we begin, let me inform you that I will be calling this bot telegram-business for the rest of this tutorial.

WHAT TELEGRAM-BUSINESS CAN DO

First off, there are two kinds of users: customers and business owners. The features of the bot are classified according to the typeof users allowed on the platform. The following includes the features of telegram-business:

CUSTOMER FEATURES:

Customers can view businesses from four different categories.
Customers can view products from any of these businesses.
Customers can place an order on a product.

BUSINESS OWNER FEATURES:

Business owners can create a catalog and add products.
Business owners will get notified when a user places an order.

Pre-Requisites

For this tutorial I’m going to be using Python3, as well as Fauna’s platform.To follow this tutorial, you’ll want to have Python installed and have an account with Fauna. If you do not have a Fauna account, you can signup on the website, here. It is in your best interest to have a fundamental knowledge of Python to follow this tutorial. I’ll also be using Cloudinary to store product images. You can sign up for a free Cloudinary account, here. Here’s a detailed list of the things we need for this bot:

Python3
A fauna account
A cloudinary account

Preparing the database

The first thing we want to do is to set up our database on Fauna. Head over to fauna.com and log in to your dashboard. Once logged in, click on the “New Database” button on the dashboard to create a new database.

This will bring you to a page just like in the image above. Fill in the required fields and click on “Save” to create a new database for our bot.

Creating Collections

Next, we’ll create three collections for each entity on our platform; Users, Businesses, and Products. Click on “New Collection.” It should take you to a new page like the one below:

Call this one Users and hit the “Save” button to create the collection. After doing that, create two other collections, Business, and Products. Once you’re done, you should now have three collections show up on the collections menu option.

Let’s move on to creating indexes for easy retrieval of information from our database.

Creating Indexes

For our e-commerce system, we’re going to have to create several indexes to help with getting the information we need faster. To create an index head over to the indexes menu option and click on the “New Index” button to create a new index. It should take you to a new page that looks similar to the one below:

The first index we want to make allows us to find users by their name. So we’ll pick the source collection, which is the User collection for this first index, and then give our index the name “user_by_name” then we choose the term we want to search on, which is the “name” of the user, and so we enter “name” in the term field, you can leave the values field empty as is. Once done, your form should look like the one below:

Next create three more indexes with the following information:

business_by_name: {source collection: Business, term: name}
product_by_business: {source collection: Product, term: sme}
business_by_category: {source collection: Business, term: category}

Generating an API_KEY

One last thing we need to get from Fauna is the API_KEY for our database to send queries to it over the internet. Head over to the Security option and click on the “New Key” option—it should take you to a new page with a form. Click “Save”, and it’ll generate a key for you to copy. Copy that key and save it in a text file somewhere we’ll use it later.

Building The Bot

Talking with BotFather

To build a Telegram bot, we must register it with Telegram’s bot father. To create your bot, open up Telegram and search for the bot father or simply click here to go to the bot father’s chat.

Once there, type “/start” to begin a conversation with the botfather, and it’ll show you a list of commands that you can use to interact with it; these commands can be typed or clicked on to execute them.

Choose the /newbot command to create a new bot. Once we do that, botfather will ask for a name and then a username. Once we do this, the botfather will provide us with information about the new bot, like the link to the bot and an access token which is what we need for now. Copy this and save it somewhere.

Scripting Telegram-Business

We'll start by creating a virtual environment for our project, opening up your command prompt, and changing the directory to your preferred location (this should preferably be a new empty folder). Once there, create a virtual environment using any desired virtual environment manager in Python. I’m using virtualenv to create one called “env” for example, I’ll run the following command:

virtualenv env

Next, we’ll activate our virtual environment and install the following python packages:

Python-telegram-bot: which helps us write code for controlling our bot.
Faunadb: which is a Python package that helps us interact with Fauna's api from our scripts.
python-dotenv: which will help us read config variables easily.
Cloudinary: a client library for our photo storage API. Make sure to sign up for a cloudinary account and get your api_key and secret from the dashboard. We'll need those later on.

We’ll start by creating the following files in our project folder:

handlers.py
main.py
config.py
.env

I’ll split the implementation of the handlers into two parts :

Customer Functionalities
Business Functionalities

We’ll start with the business functionalities, which includes the bot’s interaction with users who are business owners. The first thing we need to do is to add our tokens and keys from botFather, cloudinary and Fauna to the .env file, as follows:

BOT_TOKEN=***486**:*******-****ro
API_SECRET=-****OcAGV****
API_KEY=********21
FAUNA_KEY=f****8sZ*****J****Gd4****Q

Once this is done, we move on to the config.py file, and in there, we point some variables to these environment variables from the .env file by reading them via the python-dotenv package we installed earlier. This package allows us to read environment variables from files and even directly from the command prompt.

import os
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.getenv('BOT_TOKEN')
api_secret = os.getenv('API_SECRET')
api_key = os.getenv('API_KEY')
FAUNA_KEY = os.getenv('FAUNA_KEY')

Now, we can use these variables in our code without reading from the env file. Next, we begin with our handler methods, and these will handle how the bot interacts with the users on Telegram.

We’ll start with the handler methods responsible for managing the bot’s interaction with users who sign up to be business owners.. The file for this code is handlers.py, and import the required dependencies.

from telegram import (
    ReplyKeyboardMarkup,
    ReplyKeyboardRemove, Update,
    InlineKeyboardButton, InlineKeyboardMarkup
)
from telegram.ext import (
    CommandHandler, CallbackContext,
    ConversationHandler, MessageHandler,
    Filters, Updater, CallbackQueryHandler
)
from config import (
    api_key, sender_email,
    api_secret,
    FAUNA_KEY
)
import cloudinary
from cloudinary.uploader import upload
from faunadb import query as q
from faunadb.client import FaunaClient
from faunadb.errors import NotFound

We’ll add some of the boilerplate config for some of our dependencies, so add the following after importing all these:

# configure cloudinary
cloudinary.config(
    cloud_name="curiouspaul",
    api_key=api_key,
    api_secret=api_secret
)

# fauna client config
client = FaunaClient(secret=FAUNA_KEY)

# Define Options
CHOOSING, CLASS_STATE, SME_DETAILS, CHOOSE_PREF, \
    SME_CAT, ADD_PRODUCTS, SHOW_STOCKS, POST_VIEW_PRODUCTS = range(8)

The first config is for our Cloudinary instance, and the second for our Fauna client instance, the variables following that represent the states of the bot or at least the state that it could be in as users interact with it. This is required by the “conversationhandler” which is a method that allows us to script our bots in a way that makes their interaction with people more natural. The names of each variable slightly indicate what state they represent. For example, the SME_DETAILS state is tied to certain methods of asking the user for details of their business.

Adding Handler Methods

We’ll continue from this point by adding handler methods to our script. The first handler method we need to add is the one that handles what takes place when we initiate a conversation with the bot via the /start command.

The following lines of code are what gets called when someone uses the /start command on our bot, so add it to the handler code.

def start(update, context: CallbackContext) -> int:
    print("You called")
    bot = context.bot
    chat_id = update.message.chat.id
    bot.send_message(
        chat_id=chat_id,
        text= "Hi fellow, Welcome to SMEbot ,"
        "Please tell me about yourself, "
        "provide your full name, email, and phone number, "
        "separated by comma each e.g: "
        "John Doe, JohnD@gmail.com, +234567897809"
    )
    return CHOOSING

Look at how I return a new state of the bot’s conversation, which is one of our predefined states from earlier. This function sends back an intro message and requests information from the user.

The following state is CHOOSING, and this state is tied to another method, which takes the user input and parses it to make sure it is correct before using the info to sign a user up. Then it prompts the user to pick what kind of user he/she is i.e., a customer or business owner. Add the following lines of code to add this method:

# get data generic user data from user and store
def choose(update, context):
    bot = context.bot
    chat_id = update.message.chat.id
    # create new data entry
    data = update.message.text.split(',')
    if len(data) < 3 or len(data) > 3:
        bot.send_message(
            chat_id=chat_id,
            text="Invalid entry, please make sure to input the details "
            "as requested in the instructions"
        )
        bot.send_message(
            chat_id=chat_id,
            text="Type /start, to restart bot"
        )
        return ConversationHandler.END
    #TODO: Check if user already exists before creating new user
    new_user = client.query(
        q.create(q.collection('User'), {
            "data":{
                "name":data[0],
                "email":data[1],
                "telephone":data[2],
                "is_smeowner":False,
                "preference": "",
                "chat_id":chat_id
            }
        })
    )
    context.user_data["user-id"] = new_user["ref"].id()
    context.user_data["user-name"] = data[0]
    context.user_data['user-data'] = new_user['data']
    reply_keyboard = [
    [
        InlineKeyboardButton(
            text="SME",
            callback_data="SME"
        ),
        InlineKeyboardButton(
            text="Customer",
            callback_data="Customer"
        )
    ]
  ]
  markup = InlineKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
    bot.send_message(
        chat_id=chat_id,
        text="Collected information succesfully!..🎉🎉 \n"
        "Which of the following do you identify as ?",
        reply_markup=markup
    )
    return CLASS_STATE

This function takes the user input, parses it, and uses the result to save the user’s information onto our database on Fauna by using the query method from the Fauna library to send a post request to the Fauna API which writes to the database.

We also store some information about the user in memory with the context.user_data[] attribute - that we’ll need later in other handler methods. Lastly, we return a response as well as a new conversation state, this state (CLASS_STATE) is where we’ll determine what kind of user we’re dealing with i.e a customer or a business owner.

def classer(update, context):
    bot = context.bot
    chat_id = update.callback_query.message.chat.id
    name = context.user_data["user-name"]
    if update.callback_query.data.lower() == "sme":
        # update user as smeowner
        client.query(
            q.update(
                q.ref(q.collection("User"), context.user_data["user-id"]),
                {"data": {"is_smeowner":True}}
            )
        )
        bot.send_message(
            chat_id=chat_id,
            text=f"Great! {name}, please tell me about your business, "
            "provide your BrandName, Brand email, Address, and phone number"
            "in that order, each separated by comma(,) each e.g: "
            "JDWears, JDWears@gmail.com, 101-Mike Avenue-Ikeja, +234567897809",
            reply_markup=ReplyKeyboardRemove()
        )

        return SME_DETAILS
    categories = [  
        [
            InlineKeyboardButton(
                text="Clothing/Fashion",
                callback_data="Clothing/Fashion"
            ),
            InlineKeyboardButton(
                text="Hardware Accessories",
                callback_data="Hardware Accessories"
            )
        ],
        [
            InlineKeyboardButton(
                text="Food/Kitchen Ware",
                callback_data="Food/Kitchen Ware"
            ),
            InlineKeyboardButton(
                text="ArtnDesign",
                callback_data="ArtnDesign"
            )
        ]
    ]
    bot.send_message(
        chat_id=chat_id,
        text="Here's a list of categories available"
        "Choose one that matches your interest",
        reply_markup=InlineKeyboardMarkup(categories)
    )
    return CHOOSE_PREF

However, the function sends a different response to the user if the user identifies as a customer instead. There is a menu of categories for the customer to choose from in order to view the businesses under the chosen category. If the user identifies as a customer these categories are sent as a response to the user and a new state is returned associated with customer functionalities.

Let's add a "cancel" command handler to help users cancel their interaction with the bot at any time. Add the following function next:

# Control
def cancel(update: Update, context: CallbackContext) -> int: 
    update.message.reply_text(
        'Bye! I hope we can talk again some day.',
        reply_markup=ReplyKeyboardRemove()
    )

    return ConversationHandler.END

At this point, we can test our bot to see how it responds to our interactions. In order to test the bot, we need to register our handlers with the conversation handler method in main.py and map them to each state, as follows:

import handlers
from telegram.ext import (
    CommandHandler, CallbackContext,
    ConversationHandler, MessageHandler,
    Filters, Updater, CallbackQueryHandler
)
from config import TOKEN

updater = Updater(token=TOKEN, use_context=True)
print(updater)
dispatcher = updater.dispatcher


def main():
    conv_handler = ConversationHandler(
        entry_points=[CommandHandler('start', handlers.start)],
        states={
            handlers.CHOOSING: [
                MessageHandler(
                    Filters.all, handlers.choose
                )
            ],
            handlers.CLASS_STATE: [
                CallbackQueryHandler(handlers.classer)
            ]
        },
        fallbacks=[CommandHandler('cancel', handlers.cancel)],
        allow_reentry=True
    )
    dispatcher.add_handler(conv_handler)
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

Save this,go to your terminal, and run the bot via the main.py file as follows:

Once you run this command, you might not see any immediate prompt from the terminal until you begin interacting with the bot. Let’s go to our bot and initiate a conversation. Use the link that botFather provided you with or just search with the name of your bot in Telegram.

Once there, use the /start command, or just click the start button on the chat, with your bot to initialize a conversation. You should see your bot respond as such:

Follow the prompt, type in the required information, and send it as a message to activate the next state of the conversation, which is going to ask you to pick what kind of user you identify as, an SME owner or a customer.

Choosing the SME option prompts us to enter details about our “business” as described in the classer() method we defined earlier on. However, if we chose the customer option as our preference, then the bot responds with a list of category options to choose from.

This is as far as our bot can go, since we haven’t added the handler methods for the remaining functionalities we want. So let’s continue with scripting the bot.

The following is a series of handler methods that are responsible for all business functionalities. Add the following handler methods in the order that they are below. I am listing them out based on their functionalities, and some may involve more than one handler method:

Collecting Business Details and Storing: For this, there are two functions; the first takes user input from the last phase for a business, parses it and stores the data in memory, passes the data to the following handler method, and finally prompts the user to pick a category under which their business falls.

The second one takes all the data and uses it to create a new business document in our Faunadb instance, prompts the user to add a new product, and then returns a new
conversation state, which is associated with the handler methods responsible for adding products to the newly created business.

def business_details(update, context):
    bot = context.bot
    chat_id = update.message.chat.id
    data = update.message.text.split(',')
    if len(data) < 4 or len(data) > 4:
        bot.send_message(
            chat_id=chat_id,
            text="Invalid entry, please make sure to input the details "
            "as requested in the instructions"
        )
        return SME_DETAILS
    context.user_data["sme_dets"] = data
    # categories = [
    #         ['Clothing/Fashion', 'Hardware Accessories'],
    #         ['Food/Kitchen Ware', 'ArtnDesign'],
    #         ['Other']
    # ]
    categories = [  
        [
            InlineKeyboardButton(
                text="Clothing/Fashion",
                callback_data="Clothing/Fashion"
            ),
            InlineKeyboardButton(
                text="Hardware Accessories",
                callback_data="Hardware Accessories"
            )
        ],
        [
            InlineKeyboardButton(
                text="Food/Kitchen Ware",
                callback_data="Food/Kitchen Ware"
            ),
            InlineKeyboardButton(
                text="ArtnDesign",
                callback_data="ArtnDesign"
            )
        ]
    ]
    markup = InlineKeyboardMarkup(categories, one_time_keyboard=True)
    bot.send_message(
        chat_id=chat_id,
        text="Pick a category for your business from the options",
        reply_markup=markup
    )
    return SME_CAT

def business_details_update(update, context):
    bot = context.bot
    chat_id = update.callback_query.message.chat.id
    choice = update.callback_query.data
    # create business
    new_sme = client.query(
        q.create(
            q.collection("Business"),
            {"data":{
                "name":context.user_data["sme_dets"][0],
                "email":context.user_data["sme_dets"][1],
                "address":context.user_data["sme_dets"][2],
                "telephone":context.user_data["sme_dets"][3],
                "category":choice.lower()
            }}
        )
    )
    context.user_data["sme_name"] = context.user_data["sme_dets"][0]
    context.user_data["sme_id"] = new_sme["ref"].id()
    context.user_data["sme_cat"] = choice
    button = [[
        InlineKeyboardButton(
            text="Add a product",
            callback_data=choice.lower()
        )
    ]]
    bot.send_message(
        chat_id=chat_id,
        text="Business account created successfully, "
        "let's add some products shall we!.",
        reply_markup=InlineKeyboardMarkup(button)
    )
    return ADD_PRODUCTS

Adding Products: This involves two handler methods as well, the first one prompts the user and gives instructions on how the product can be added, while the second one takes the user input, parses it and uses it to create a new product, by adding it as a new document to our Product collection on our Fauna instance.

def add_product(update, context):
    bot = context.bot
    chat_id = update.callback_query.message.chat.id
    bot.send_message(
        chat_id=chat_id,
        text="Add the Name, Description, and Price of product, "
        "separated by commas(,) as caption to the product's image"
    )
    return ADD_PRODUCTS

def product_info(update: Update, context: CallbackContext):
    data = update.message
    bot = context.bot
    photo = bot.getFile(update.message.photo[-1].file_id)
    file_ = open('product_image', 'wb')
    photo.download(out=file_)
    data = update.message.caption.split(',')
    # upload image to cloudinary
    send_photo = upload('product_image', width=200, height=150, crop='thumb')
    # create new product
    newprod = client.query(
        q.create(
            q.collection("Product"),
            {"data": {
                    "name":data[0],
                    "description":data[1],
                    "price":float(data[2]),
                    "image":send_photo["secure_url"],
                    "sme":context.user_data["sme_name"],
                    "sme_chat_id": update.message.chat.id,
                    "category":context.user_data["sme_cat"]
                }
            }
        )
    )
    # add new product as latest
    client.query(
        q.update(
            q.ref(q.collection("Business"), context.user_data["sme_id"]),
            {"data": {
                "latest": newprod["ref"].id()
            }}
        )
    )
    # context.user_data["product_data"] = newprod['data']
    button = [[InlineKeyboardButton(
        text='Add another product',
        callback_data=context.user_data["sme_name"]
    )]]
    update.message.reply_text(
        "Added product successfully",
        reply_markup=InlineKeyboardMarkup(button)
    )
    return ADD_PRODUCTS

This concludes the business part of the bot. We will now add more handler methods to cover the customer functionalities, as follows:

View Businesses From any Category: This involves a handler method that takes the user’s choice and uses our business_by_category index to find all businesses in that category and then displays a list of the businesses with their latest merchandise as a thumbnail, along with two options.

## CUSTOMER
def customer_pref(update, context):
    bot = context.bot
    chat_id = update.callback_query.message.chat.id
    data = update.callback_query.data
    print(data)
    # get all businesses in category
    try:
        smes_ = client.query(
            q.map_(
                lambda var: q.get(var),
                q.paginate(
                    q.match(
                        q.index("business_by_category"),
                        str(data).lower()
                    )
                )
            )
        )
        print(smes_)
        for sme in smes_["data"]:
            button = [
                [
                    InlineKeyboardButton(
                        text="View Products",
                        callback_data=sme["data"]["name"]
                    )
                ],
                [
                    InlineKeyboardButton(
                        text="Select for updates",
                        callback_data="pref"+','+sme["data"]["name"]
                    )
                ]
            ]
            if "latest" in sme['data'].keys():
                thumbnail = client.query(q.get(q.ref(q.collection("Product"), sme["data"]["latest"])))
                print(thumbnail)
                bot.send_photo(
                    chat_id=chat_id,
                    photo=thumbnail["data"]["image"],
                    caption=f"{sme['data']['name']}",
                    reply_markup=InlineKeyboardMarkup(button)
                )
            else:
                bot.send_message(
                    chat_id=chat_id,
                    text=f"{sme['data']['name']}",
                    reply_markup=InlineKeyboardMarkup(button)
                )
    except NotFound:
        button = [[
            InlineKeyboardButton(
                text="Select another Category?",
                callback_data="customer"
            )
        ]]
        bot.send_message(
            chat_id=chat_id,
            text="Nothing here yet",
            reply_markup=InlineKeyboardMarkup(button)
        )
        return CLASS_STATE
    return SHOW_STOCKS

View Products: This is quite self-explanatory, and it involves listing out all products belonging to any business that the user has decided to view. We are able to display all products from a business with the aid of the products_by_business index we created on our Fauna instance earlier, what this means is that we can send a query to fetch all the products that a business has on its catalogue (with the products_by_business index) and then display the results to the user.

def show_products(update, context):
    bot = context.bot
    chat_id = update.callback_query.message.chat.id
    data = update.callback_query.data
    if "pref" in  data:
        data = data.split(',')[0].replace(' ', '')
        print(data)
        user = client.query(
            q.get(
                q.ref(
                    q.match(q.index('user_by_name'), context.user_data['user-data']['name']),

                )
            )
        )
        # update preference
        client.query(
            q.update(
                q.ref(
                    q.collection('User'), user['ref'].id()
                ),
                {'data': {'preference': user['data']['preference']+data+','}}
            )
        )
        button = [
            [
                InlineKeyboardButton(
                    text="Vieew more businesses category",
                    callback_data='customer'
                )
            ]
        ]
        bot.send_message(
            chat_id=chat_id,
            text="Updated preference successfully!!"
        )
        return CLASS_STATE
    products = client.query(
        q.map_(
            lambda x: q.get(x),
            q.paginate(
                q.match(
                    q.index("product_by_business"),
                    update.callback_query.data
                )
            )
        )
    )
    # print(products)
    if len(products) <= 0:
        bot.send_message(
            chat_id=chat_id,
            text="'Nothing here yet, user hasn't added any products!, check back later"
        )
        return CLASS_STATE
    for product in products["data"]:
        context.user_data["sme_id"] = product['data']['sme']
        button = [
            [
                InlineKeyboardButton(
                    text="Send Order",
                    callback_data="order;" + product["ref"].id()
                )
            ],
            [
                InlineKeyboardButton(
                    text="Contact business owner",
                    callback_data="contact;" + product["data"]["sme"]
                )
            ]
        ]
        bot.send_photo(
            chat_id=chat_id,
            photo=product["data"]["image"],
            caption=f"{product['data']['name']} \nDescription: {product['data']['description']}\nPrice:{product['data']['price']}",
            reply_markup=InlineKeyboardMarkup(button)
        )
    return POST_VIEW_PRODUCTS

This block of code is responsible for fetching all the products from a business and displaying them to the user, with the option of placing an order or contacting the business owner.

Place Order and Contact Details of Business Owner: The following block is responsible for placing an order and providing the customer with the business owner’s details.When a user places an order, the bot sends a message to the business owner containing information about the product that will sold, and the prospective buyer’s Telegram contact.

def post_view_products(update, context):
    bot = context.bot
    chat_id = update.callback_query.message.chat.id
    data = update.callback_query.data
    product = client.query(
        q.get(
            q.ref(
                q.collection("Product"),
                data.split(';')[1]
            )
        )
    )["data"]
    if "order" in data:
        bot.send_message(
            chat_id=product['sme_chat_id'],
            text="Hey you have a new order"
        )
        bot.send_photo(
            chat_id=product['sme_chat_id'],
            caption=f"Name: {product['name']}\n\nDescription: {product['description']}\n\nPrice: {product['price']}"
            f"\n\n Customer's Name: {context.user_data['user-name']}",
            photo=product['image']
        )  
        bot.send_contact(
            chat_id=product['sme_chat_id'],
            phone_number=context.user_data['user-data']['telephone'],
            first_name=context.user_data['user-data']['name']
        )
        bot.send_message(
            chat_id=chat_id,
            text="Placed order successfully"
        )
    elif 'contact' in data:
        sme_ = client.query(
            q.get( 
                q.match(
                    q.index("business_by_name"), 
                    product['sme']
                )
            )
        )['data']
        bot.send_message(
            chat_id=chat_id,
            text=f"Name: {sme_['name']}\n\nTelephone: {sme_['telephone']}\n\nEmail:{sme_['email']}"
        )

Testing The Bot

We can save the changes to our handlers.py file and then move on to register the newly added methods to our conversation handler in main.py as with the first few functions, as follows:

import handlers
from telegram.ext import (
    CommandHandler, CallbackContext,
    ConversationHandler, MessageHandler,
    Filters, Updater, CallbackQueryHandler
)
from config import TOKEN

updater = Updater(token=TOKEN, use_context=True)
print(updater)
dispatcher = updater.dispatcher


def main():
    conv_handler = ConversationHandler(
        entry_points=[CommandHandler('start', handlers.start)],
        states={
            handlers.CHOOSING: [
                MessageHandler(
                    Filters.all, handlers.choose
                )
            ],
            handlers.CLASS_STATE: [
                CallbackQueryHandler(handlers.classer)
            ],
            handlers.SME_DETAILS: [
                MessageHandler(
                    Filters.all, handlers.business_details
                )
            ],
            handlers.SME_CAT: [
                CallbackQueryHandler(handlers.business_details_update)
            ],
            handlers.ADD_PRODUCTS: [
                CallbackQueryHandler(handlers.add_product),
                MessageHandler(Filters.all, handlers.product_info)
            ],
            handlers.CHOOSE_PREF: [
                CallbackQueryHandler(handlers.customer_pref)
            ],
            handlers.SHOW_STOCKS: [
                CallbackQueryHandler(handlers.show_products)
            ],
            handlers.POST_VIEW_PRODUCTS: [
                CallbackQueryHandler(handlers.post_view_products)
            ]
        },
        fallbacks=[CommandHandler('cancel', handlers.cancel)],
        allow_reentry=True
    )
    dispatcher.add_handler(conv_handler)
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

Update the code in main.py so it has the other functions we added, as shown above.When completed, we can run our code from the cmd, like before, to test our bot.

Once it's up and running, head over to the bot on Telegram and create a business and add products. You could also use another telegram account to interact with the bot as a customer and place orders.

The second image shows what the business owner sees each time a customer places an order.

Conclusion

In this article, we’ve seen how to use Fauna’s serverless platform to create and host a database, along with indexes and collections. We saw how to generate an API key for communicating with our database from within other python apps, which in this case was telegram-business. We saw how to build a telegram bot from scratch using Python and the required libraries.

The demo from this article isn’t the end for telegram-business however, I’ll be adding more features and deploying it live soon enough. I’m hoping this article has inspired you to think of new ways to create solutions to problems around you, and when you finally find a solution you know you can always count on Fauna to help host your data without hassle like it has helped us in this article.

Building a QuizGenerator With Flask and Fauna

Curious Paul — Tue, 16 Feb 2021 18:54:17 +0000

Over the past month or two, I’ve had quite the experience working with FaunaDb, and its many features that don’t fail to amuse me a fair amount each time. I’m primarily a backend developer and one important thing I have to deal with is serving pre-formatted data to clients that request that data.

An example would be having to serve paginated data to clients that need to render data in pages (say frontend of an eCommerce with a list of fancy shoe products). FaunaDb makes this task easy with its paginate function, and in this article, I’ll be going over how to build a Quiz generator using Fauna to serve the data in paginated format.

Setting up the database with FaunaDb
Building Our flask App
Conclusion

Setting up the database With FaunaDb

If you’d like to follow along, sign up for a Fauna account. Let’s begin by creating a new database on Fauna, two collections Quiz, and Category, as well as some indexes to help with data retrieval. Go to your Fauna dashboard and create a database as follows:

I’m calling it “quizgen” but you can call it whatever you want, hit the Save button, and it should take you to a new page with the option to create a new collection on there. Click the button to create a new collection to create a new collection.

The first collection I created is called Categories, and this is where we’ll store the different categories of quiz questions that we’ll have on the quiz generator.

Hit the Save button to save your new collection, and create a second one called quiz ;this is where we’ll actually store our quizzes. Let's look at the structure of our quiz documents (documents in FaunaDb refer to rows in a table(collection) in relational databases).

QUIZ Document:

quiz_body: this field contains the question
A: field representing option A, there are four options in total hence a field for each one.
answer: this field holds the option that is the correct answer to the question.

Category Document:

Name: this is the only field in a category document, and it’s just a string value that holds the name of the category.

Populating The Categories Collection

The next thing we would do is to add our categories to the categories collection. We’re going to do this manually from the dashboard on the website since the document only has one string field and it’s simple enough for a small number of category documents. We’ll create three documents in the collection with names: art, science, and entertainment. To do this head over to the collections options on the dashboard and choose the categories collection, it should show you the option to create a new document.

It should bring you to this new area, with an editor where you can type syntax to create new documents. In there type in the following, to create a new document to represent the science category:

Click the save button to save, and repeat this same step, for the remaining two categories. Once you are done, all the documents should be displayed on the collections page for that particular collection.

Creating Indexes

Let’s create indexes to help with data retrieval from the database. For our quiz app we’ll have two indexes, described as follows:

We want to be able to get a list of all quizzes in a certain category, so we’ll make an index for that, call it quiz_by_category.
We also want to be able to get a category document by name. We'd need that to tag each quiz by the name of its category, as we will see later on. We’ll call this category_by_name

To create an index on our Fauna database, you head over to the indexes section and click the create a new index button, this page should look something like this once you click the New Index button\

On this page, we see a couple of fields to fill:

Source Collection: This is what collection we hope to use the index we’re about to create on, in this case, we’re using the index(category_by_name) on the *category * collection.
Index Name: This is where we name our index, by giving it a descriptive name - such as -category_by_name.
Terms: since we say we need to get category by name, we need to be able to specify the name of the category we want to get with the index, and this is where this field comes in. So in this instance, we simply type in “name” this correlates with the name field on the category collection. When we specify the name of the category we wish to fetch with the index, it will use whatever we type here (which should be the name of a field on the collection; much like a column on a table with relational databases), to look for the document with that particular value in that field.
Values: Once we find the document(s) with the index, should the whole document be returned or perhaps just its reference ID, or maybe one of its field values; we can specify what fields or attributes we want from the query. And for the purposes of this tutorial, we will choose to specify the name field of the document(s) that the query returns. Leaving this option empty, makes the query return the reference to each of the documents instead, which can then be used to query the collection for the documents.

Once you’ve filled the form, it should like what I have below:

To create the new index hit Save, and you should now see a new index has been created. We can test this index, as you should now see a small search field right on that page after saving the index, simply type in any of the category names we created in the category collection, and hit the search button to query the database with that index, and it should return whatever was specified in the values option from the last step (in which case was the name of the category).

Let’s create one more index to fetch quizzes by category, so repeat the same steps and fill in the required fields as follows:

So note the differences, here we specified the source collection as Quiz since that’s where our data will be coming from and this also doesn’t specify any values, which means we want the reference for each quiz item from the query.

Creating an API key

In order to be able to communicate with Fauna and perform read and writes to our database from our flask app, we need to generate a key, from the security tab on the dashboard, as follows:

Leave everything as is and hit the save button to generate a new key, once it generates it copy it and save it as an environment variable with the name I saved mine with the name “FAUNA_SECRET” in a .env file, but you can use whatever you want.

Building Our Flask App

The flask app will have a fairly basic structure, it’s not going to be a REST API, it’ll render its own templates and serve data to the template itself. If you’re new to Flask kindly take a crash course or view the official docs, it’s intuitive and it’s a great place to begin your flask journey.

I have created a new folder called “quizgen/” and in there I have created a virtual environment to install my dependencies, for this app we’ll need to install Flask, Fauna client for python, and python-dotenv. Once you have activated the virtual environment, you can install the required packages as follows:

pip install flask faunadb python-dotenv

Once that’s done, we’ll make two folders, one to hold our HTML files, and one to hold static files, like images and stylesheets. The first one is called /templates and it’s a name chosen by Flask by default, so Flask will automatically look for HTML files in the /templates folder, the second one is called /static and it’s where our static files go. We’ll also create a file for our Flask app, I call mine app.py as well as a .env file where we’ll store our environment variables. Your folder structure should like the one below if you did all these correctly:

Here’s the code for our flask server in app.py. It has a single route and it renders a template named index.html which is where our interface is built. The flask server will look for this HTML file in the templates folder we created initially so it’s important to name it correctly "templates'' not “template” (all lowercase).

from flask import Flask, render_template, url_for, request
from faunadb import query as q
from faunadb.client import FaunaClient
from dotenv import load_dotenv
import os

load_dotenv() # loads env variables from .env files
client = FaunaClient(secret=os.getenv('FAUNA_SECRET'))

# routes
@app.route("/")
@app.route("/index")
def index():
    return render_template("index.html")

if __name__ == '__main__':
    app.run(debug=True)

This will be edited later on but for now, let’s leave it as so. We’ll now move on to building our interface.

Building The Interface (Frontend)

As we saw in the last part, the server renders a file called “index.html” which we have in fact - not created, so let’s do that. Again all HTML files go in the templates folder so go in the templates folder and create index.html. We’ll add some HTML markup there for our quiz frontend, we’ll also need to add styling, and to do that we’ll add a new file inside of the static/ folder, I’ll call it style.css, and we’ll write some CSS in there for the quiz app. We might also need some JavaScript so I’ll add a new file called script.js in the same directory. With this we should have a folder structure resembling the one below:

In the index.html we simply have the quiz categories which users can select to see a list of questions and a form that they can use to contribute the questions archive. Put the following in the index.html file.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>QuizGenerator</title>
    <link rel="preconnect" href="https://fonts.gstatic.com">
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+TC:wght@100;300;400;900&display=swap" rel="stylesheet">
    <link rel="stylesheet" href="{{url_for('static', filename='style.css')}}">
</head>
<body>
    <div class="container">
        <h1 class="header-text">Quiz Generator</h1>
        <p>
            Welcome user, to begin pick from a list of categories to view the questions
            we have in our archive.
        </p>
        <div class="categories">
            <a href="{{url_for('get_quiz_by_category', category='science')}}">
                <div id="science" class="catitem">
                    <div class="imgdiv">
                        <img src="../static/undraw_science_fqhl.svg" alt="">
                    </div>
                    <p>
                        Lorem ipsum dolor sit amet consectetur adipisicing elit. Nemo, expedita?
                    </p>
                </div>
            </a>
            <a href="{{url_for('get_quiz_by_category', category='art')}}">
                <div id="art" class="catitem">
                    <div class="imgdiv">
                        <img src="../static/undraw_art_museum_8or4.svg" alt="">
                    </div>
                    <p>
                        Lorem ipsum dolor sit amet consectetur adipisicing elit. Nemo, expedita?
                    </p>
                </div>
            </a>

            <a href="{{url_for('get_quiz_by_category', category='entertainment')}}">
                <div id="entertainment" class="catitem">
                    <div class="imgdiv">
                        <img src="../static/undraw_horror_movie_3988.svg" alt="">
                    </div>
                    <p>
                        Lorem ipsum dolor sit amet consectetur adipisicing elit. Nemo, expedita?
                    </p>
                </div>
            </a>
        </div>

        <div class="contribute">
            <h2>Help grow this platform, by contributing to our archive</h2>
            <form action="{{url_for('add_quiz')}}", method="POST">
                <span>Pick a category</span>
                <select name="category" id="" aria-placeholder="Pick a category">
                    <option value="">--Please choose an option--</option>
                    <option value="science">Science</option>
                    <option value="art">Art</option>
                    <option value="entertainment">Entertainment</option>
                </select>
                <div class="quiz-details">
                    <h3>Give us the details</h3>
                    <textarea name="quiz-body" id="" placeholder="Type in the question"></textarea>
                    <div class="quiz-options">
                        <input type="text" name="A" id="" placeholder="Option A">
                        <input type="text" name="B" id="" placeholder="Option B">
                        <input type="text" name="C" id="" placeholder="Option C">
                        <input type="text" name="D" id="" placeholder="Option D">
                        <br>
                        <input type="text" name="ans" id="" placeholder="Tell us the answer">
                    </div>
                </div>
                <button type="submit">Submit</button>
            </form>
        </div>
    </div>
<script src="{{url_for('static', filename='script.js')}}"></script>
</body>
</html>

Pretty basic HTML syntax, note that the links, form action, and HREFs in the code use the {{url_for}}, this is flask’s template engine(Jinja2) directive which is what helps to link to the server’s endpoint(s) directly, so we don’t have to use javascript to make calls to the server.

Next, we’ll add some styling to the style.css file as follows:

body {
    font-family: 'Noto Sans TC', sans-serif;
    background-color: #f5f5f5;
}

.header-text {
    text-align: center;
}

.container {
    width: 80%;
    margin:0 auto;
    padding: 0;
    overflow:hidden;
    text-align: center;
}

.categories {
    display: flex;
    flex-direction: column;
    align-items: center;
}

.catitem {
    width: 15rem;
    border: 1px dashed #333;
    height: 15rem;
    border-radius: 10px;
    padding:0 10px 0 10px;
    margin-bottom: 2rem;
    box-shadow: 5px 5px 10px #acabab;
    transition: 0.35s ease-in-out;
}

.catitem:hover {
    cursor: pointer;
    padding:0 5px;
    transform:scale(0.9);
}

.imgdiv img {
   height: 100px;
   width: 100%;
}

.imgdiv {
    width: 100%;
    background-color: #777;
    opacity: 0.5;
    box-shadow: 5px 5px 3px #333;
}

.categories:last-child {
    margin-bottom: 0;
}

.contribute {
    display:flex;
    flex-direction: column;
    align-items: center;
}

.contribute form select{
    padding:5px;
    border:none;
    background-color: f4f4f4;
    border-radius: 2px;
}

.contribute textarea {
    margin: 0 auto;
    width: 80%;
    border: none;
    background-color: #f4f4f4;
    border-radius: 5px;
    box-shadow: 2px 2px 4px #35acfc;
    margin-bottom: 10px;
}

.quiz-details {
    display: flex;
    flex-direction: column;
    margin-top:5px;
}

.quiz-details input {
    margin-bottom: 10px;
    padding: 7px;
    background-color: #f4f4f4;
    box-shadow: 2px 2px 4px #35acfc;
    border:none;
    border: 5px;
}

.quiz-details:last-child{
    margin-bottom: none;
}

.contribute button {
    border-radius: 10px;
    background-color:#35acfc;
    border:1px solid #fff;
    padding:5px;
    color:#fff;
}

.quiz-container {
    width: 80%;
    margin: 0 auto;
    background: #f4f4f4;
}

.quiz-section {
    display: flex;
    flex-direction: column;
}

.quiz-container:last-child{
    margin-bottom: 0;
}

.quizitem {
    padding:5px 8px;
    background: #6fc4fc;
    border-radius: 10px;
    width: 50%;
    margin-bottom: 20px;
}

#science {
    background-color: #fcc435;
}

#art {
    background-color: #35acfc;
}

#entertainment{
    background-color: #56fc35;
}

@media (min-width:768px) {
    .catitem {
        width: 40rem;
    }
}

I also added some effects with javascript, so add the following in script.js

const _science = document.getElementById('science')
const _art = document.getElementById('art')
const _entertainment = document.getElementById('entertainment')


_science.addEventListener('click', ()=>{
    _art.style.transition = '0.8s'
    _art.style.transform = 'translateY(500%)'
    _entertainment.style.transition = '0.8s'
    _entertainment.style.transform = 'translateY(500%)'
})

_art.addEventListener('click', ()=>{
    _science.style.transition = '0.8s'
    _science.style.transform = 'translateY(500%)'
    _entertainment.style.transition = '0.8s'
    _entertainment.style.transform = 'translateY(500%)'
    _art.style.transform = 'translateY(-120%)'
})

_entertainment.addEventListener('click', ()=>{
    _art.style.transition = '0.8s'
    _art.style.transform = 'translateY(500%)'
    _science.style.transition = '0.8s'
    _science.style.transform = 'translateY(500%)'
    _entertainment.style.transform = 'translateY(-220%)'
})

Once we have all these, we can start our server and hit the /index route to see our page with its design. So from the terminal run :

python app.py
Once the server is running, go to localhost:5000/ or localhost:5000/index to see the page.

Here’s what it should like if all goes well. Try clicking on any of the categories to see the effect. Now it’s time to add the rest of the functionalities. Currently, if you click any of the categories it does nothing other than making the other ones disappear for the sake of emphasis. That’s certainly not the only thing we want to happen when we choose a category, we also want to see the list of questions once we click on any category. We also want to be able to send new quizzes to our database from the form we added on the homepage. Let’s start with that.

Handling new quiz entries

We want users to be able to contribute to the quiz archive, and for that reason, we added a form to the homepage and specified a form-action which is where the form data is to be sent, if you check back on the index.html file we made earlier you should see it’s specified as follows:

This means the form data is to be sent to an endpoint(handler method) called add_quiz, so let’s add that endpoint, shall we. In the app.py file, we’ll add a new endpoint that takes in data from the form and sends it to our Fauna database, as follows:

@app.route("/addquiz", methods=['POST'])
def add_quiz():
    _data = request.form
    # search for category specified using index
    get_category = client.query(q.get(q.match(q.index('category_by_name'), _data['category'])))
    new_quiz = client.query(
        q.create(q.collection('Quiz'), {
            "data":{
                "quiz_body":_data['quiz-body'],
                "A": _data["A"],
                "B": _data["B"],
                "C": _data["C"],
                "D": _data["D"],
                "answer": _data["ans"],
                "category": get_category['data']['name']
            }
        })
    )

    return {
        "status":"sent"
    }, 200

Observe that the name of the handler method is add_quiz which is what is specified in the form-action, and not addquiz as is with the route for the endpoint, so make sure to specify the handler method’s name and not the name used with the URL Let’s test this if your server stopped running just re-run it and go to the homepage and fill in a quiz question, hit the submit button if all goes well you should see the happy response from the server, as follows:

You can go back to the homepage if you wish to fill in another question, which you probably should for the sake of further tests, as we will see later on.

Fetching Quizzes By Category and Pagination

Once a category is chosen on the homepage we want the list of quizzes under that category, so for that, I’ll create a new endpoint in app.py as follows:

@app.route("/quizbycategory", defaults={'category':None}, methods=['POST'])
@app.route("/quizbycategory/<category>")
def get_quiz_by_category(category):
    if request.method == 'GET':
        # get categoruy
        get_category = client.query(q.get(q.match(q.index('category_by_name'), category)))
        query = client.query(
            q.map_(
                lambda var: q.get(var),
                q.paginate(
                    q.match(
                        q.index("quiz_by_category"),
                        get_category['data']['name']
                    ),
                    size=3
                )
            )
        )
        result = [i['data'] for i in query['data']]
        _vars['category_name'] = category
        if 'after' in query.keys():
            _vars['after'] = query['after'][0]
        #print(_vars)
        print(query)
        return render_template('quizpage.html', result=result)

This endpoint has two possible forms, it may or may not be called with the additional query parameter , I do this so I can use the same endpoint for two different purposes; one is to retrieve data from the database, and the other is to move between pages. The code displayed above shows the first part of these, which is to get data from the database (which in this case is to get the quizzes from the database when a category is selected. Earlier in the index.html file, we wrapped each category in a tag with its HREF property set to this endpoint(the one with the placeholder), with the name of the category as the query parameter, as shown below:

So once each one is clicked a GET request is sent to that endpoint. On the endpoint, we get the category specified by the query parameter from the request, and a query is sent to our Fauna database to get the category with that name, and then we send a new query to fetch all quizzes that are in that category, using our quiz_by_category index. We then use Fauna’s paginate function to paginate the received data into sections of 3 using the size parameter, so the query returns an array of three items, which is what we will display per page.

We use the map function to map the lambda function (which basically fetches the actual document), to each item in the array that’s returned from the paginate function, because the paginate function returns the reference of each item it finds by default instead of the document, which is what we’d need to get the quiz info.
In addition to the array containing the items found from the query, Fauna’s paginate function also includes a cursor, as the name implies it points to the reference of the document that begins the next set of paginated data. Usually, the returned data looks like this:

Observe the cursor called after and the data which is what contains our quiz documents. We need to store this after cursor because we’ll need it to query for the next page of data. We also need to keep track of the current category, so I created a dictionary to hold our temporary values for us right above the first endpoint, as such:

Note that there’s also a before cursor here, it is used to refer to the last item from the last page so we can go back to a previous page, it’s not part of the returned data as shown above because there’s nothing before the first set of paginated data. When you reach the end of all the data, it doesn’t return an after cursor but only a before cursor. Lastly, we return a new template for our quizzes called quizpage.html so head over to the templates folder and create a new file called quizpage.html and add the following markup (PS: we already added styling for this page in style.css earlier, score points to you if you noticed)

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>QuizPage- {{result[0]['category']}}</title>
    <link rel="stylesheet" href="{{url_for('static', filename='style.css')}}">
</head>
<body>
    <div class="quiz-container">
        <div class="heading">
            <h1>
                Category: {{result[0]['category']}}
            </h1>
        </div>
        <div class="quiz-section">
            {% for item in result %}
                <div class="quizitem">
                    {{item.quiz_body}}
                    <div class="quiz-options">
                        <input type="radio" id="A">
                        <label for="A">A. {{item.A}}</label><br>
                        <input type="radio" id="B">
                        <label for="B">B. {{item.B}}</label><br>
                        <input type="radio" id="C">
                        <label for="C">C. {{item.C}}</label><br>
                        <input type="radio" id="D">
                        <label for="D">D. {{item.D}}</label><br>
                    </div>
                    <div class="quiz-info">
                        <span><h3>Ans: {{item.answer}}</h3></span>
                    </div>
                </div>
            {% endfor %}
        </div>

        <div class="transit-pages">
            <form action="{{url_for('get_quiz_by_category')}}" method="POST">
               <button type="submit" name="next" class="transit-btn">Next>></button>
               <button type="submit" name="prev" class="transit-btn">Prev<<</button>
            </form>
        </div>
    </div>

</body>
</html>

Once you have all these, save and re-run your server, before trying it out you may want to add some quizzes, with the form on the homepage. Once that’s done go to the homepage and click on the category with some quizzes in it to see the quizzes displayed as such:

Note the form at the bottom of quizpage.html, with the two buttons Next and Prev, we will use those to send requests to get next or previous data sets.

Moving between pages

In order to move between pages, we make use of the cursors and in the last step we store our cursor (after cursor) in a dictionary, which we can access anywhere we need it. To this effect we added two buttons into a little form we added to the quizpage.html file. These submit buttons, send a POST request to the second form of the endpoint (URL) mentioned in the previous section. As such the code to handle this lies under the elif block, in continuation of the code in the previous sections section, as follows:

elif request.method == 'POST':
        if 'next' in request.form.keys():
            get_category = client.query(q.get(q.match(q.index('category_by_name'), _vars['category_name'])))
            query = client.query(
                q.map_(
                    lambda var: q.get(var),
                    q.paginate(
                        q.match(
                            q.index("quiz_by_category"),
                            get_category['data']['name']
                        ),
                        size=3,
                        after=_vars['after']
                    )
                )
            )
            result = [i['data'] for i in query['data']]
            if 'before' in query.keys():
                _vars['before'] = query['before'][0]
            if 'after' in query.keys():
                _vars['after'] = query['after'][0]
            return render_template('quizpage.html', result=result)
        if 'prev' in request.form.keys():
            #print(_vars)
            get_category = client.query(q.get(q.match(q.index('category_by_name'), _vars['category_name'])))
            query = client.query(
                q.map_(
                    lambda var: q.get(var),
                    q.paginate(
                        q.match(
                            q.index("quiz_by_category"),
                            get_category['data']['name']
                        ),
                        size=3,
                        before=_vars['before']
                    )
                )
            )
            result = [i['data'] for i in query['data']]
            if 'after' in query.keys():
                _vars['after'] = query['after'][0]
            if 'before' in query.keys():
                _vars['before'] = query['before'][0]
            return render_template('quizpage.html', result=result)

Here, we check to see if the next button or the prev button has been pressed, and we specify the after cursor in our query, in the event that that the next button was pressed, once we receive our results from the query we prepare the data and re-render quizpage.html with the newly returned data, which should now contain the next set of paginated data, thanks to our cursor, we also make sure to set new values for our after and before cursor, if the current set isn’t the last set of data.
We repeat the same thing, for when the prev button is pressed.

Once you’re done with this you can go back to the quiz pages and click the next button to see more quizzes. Make sure you have enough quizzes ( at least one extra quiz if anything) because we didn’t add a check to see if the query returns an empty list or not. You should see that it loads the next set of quizzes, and if you click the prev button it should take you to the previous page. You can add questions to other categories and try them out too.

Conclusion

In this article, we’ve covered some interesting concepts of data retrieval with Fauna’s API, and data handling with our flask server and Fauna’s suite of functions including the paginate function. The quiz generator we built will be hosted live for public use for free and can be accessed via this link, you can also find the source code here on github. If you have any questions about Fauna or Flask or this tutorial please leave a comment. You can also reach out to me on twitter, via @curiouspaul2, or on github @curiouspaul1.

GraphQL By Example: With Graphene, Flask, and Fauna

Curious Paul — Tue, 12 Jan 2021 22:30:21 +0000

Let’s talk about GraphQL shall we?. In this article, I’ll be going over how to create simple GraphQL servers the conventional way, with web frameworks (Flask in particular), and then later in the article, we’ll observe how to make things easier by creating GraphQL servers the serverless way using Fauna’s seamless GraphQL integration features.

Who this article is for

This article is in general for intermediate web developers and more so for those who are looking for hands-on experience with building GraphQL servers. I can’t exactly put a cap on the kinds of developers who would be reading this, but for the sake of having a great experience reading this, it’s presumed that you already know a thing or two about GraphQL (not necessary to have built a GraphQL server), and can already build a REST server, you understand GraphQL query syntax to some extent if you’re unfamiliar here’s the docs to help you get started. Regardless of what kind of developer you are, I hope this helps you in any way it can.

Also If you’re already comfortable with building a GraphQL server from scratch in Flask, you can skip this first part and move on to serverless graphql APIs with Fauna.

Here’s a table of contents to help put things into perspective as regards what we’ll be doing in this article.

A brief introduction to GraphQL
Building a GraphQL server with Flask and Graphene
Serverless GraphQL server with Fauna

A Brief Introduction To GraphQL

GraphQL is a query language for APIs. In other words, it’s the syntax that you write in order to describe the kind of data that you want from APIs. What this means for you as a backend developer is that with GraphQL, you are able to expose a single endpoint on your server to handle GraphQL queries from client applications, as opposed to the many endpoints you’d need to create to handle specific kinds of requests with REST and in turn serve static data from those endpoints. If a client needs new data that isn’t already provisioned you’d need to create a new endpoint for it and update the API docs. GraphQL makes it possible to send queries to a single endpoint, these queries are then passed on to the server to be handled by the server’s predefined resolver functions and the requested information can be provided over the network.

To help illustrate, consider a simple note-app, one where users can sign-up to create as many notes as they like, nothing fancy. A typical REST API built for this would have multiple endpoints to handle writes to the database (POSTs and PUTs), as well as endpoints to retrieve data from the database (GETs).
The diagram below helps to illustrate what a typical REST workflow might be like between client applications and servers with their databases.

As observed clients have to interact with the server via multiple communication channels (endpoints) exposed by the server. Consumers of the API, have no control over what data gets returned when they request data via (GET) protocol. With GraphQL however, clients can in effect prescribe how the data they want should look like or at least what it must contain via these “queries”, GraphQL queries to be precise. The diagram below helps to put things into perspective.

Observe that the requests are still being sent over HTTP, hence POSTS, and GETs are still valid kinds of requests with GraphQL servers, the only difference is that you can customize your requests with GraphQL queries, as opposed to JSON or query parameters to get whatever kind of data you want or send data. Because it’s customizable on the grounds of it being a query syntax you get to decide what data you want and get only what you requested from the backend. GraphQL is a revolutionary tool in web-development If you’d like to find out more about GraphQL and get some fundamental knowledge about the tool you can click here to go to the docs.

Let’s now begin our journey by seeing how to build a simple note-app GraphQL server with Flask, and Graphene then see how we can make our lives easier with serverless by leveraging Fauna's GraphQL API.

GraphQL with Python (Flask and Graphene)

We’ll be building a simple note-app web server that’s capable of handling GraphQL queries with Flask (a Python web framework for building web servers) and Graphene (which is a python library that adds GraphQL support to python and allows you write GraphQL schemas in python). To be able to follow along, you must have Python installed, and have some previous experience in both Python and Flask.

Hands-on

We’ll begin by creating a virtual environment for our project and install the dependencies we need inside of the virtual environment, with virtualenv. Make a new folder called “noteapp” and cd into that folder from the terminal or cmd (on Windows) and create a new virtualenv there as follows:

virtualenv env

Next, we need to activate the virtual environment before we can install our dependencies in it. We do this by calling the “activate.bat” script in the virtualenv. I’m on Linux so this is done as follows:

source env/bin/activate

Once this is done you should see the name of the environment prefix the current directory path on the terminal (usually in brackets), as shown here

Once this is done we can use pip to install the required packages for this project. We’ll install: Flask, Sqlalchemy, Flask-graphql, Bcrypt, Flask-Jwt-Extended, Python-dotenv, Graphene, and graphene_sqlalchemy as follows:


 install flask  sqlalchemy  flask-graphql  graphene  python-dotenv  flask-jwt-extended  bcrypt  graphene_sqlalchemy

As of now, our folder should only contain a folder called “env/” since that’s what we called our virtualenv. Let’s create some of the files we’ll be needing for the app.
- core/: add a new folder called core/ to “noteapp” as a sibling folder to env/. This folder will house our server app’s instance and its config
- core/init.py: In this new folder add a dunder(double underscore) init file. This is where we’ll add our flask app instance, some config as well as our views.
- extensions.py: outside of core/ add a new file called extensions.py it’ll hold instances of some extensions we’ll be using alongside our server.
- models.py: let’s also add a file to hold our models for the database since we’re using an ORM (sqlalchemy)
- schema.py: this is where we’ll define our graphql schema using graphene
- data.py: this file simply creates our database and tables as defined by the models in models.py
- run.py: this file is what we use to run our flask app.
- .env: this is an env file that holds environment variables to be used by our app.

If this folder structure is quite confusing, kindly check out my other article on how to build modularized flask apps, which should help clear things out.
If you did it correctly your folder structure should look like this:

Let’s now take a look at each one and see what goes into them. Disclaimer!: as a quick reminder, this is not a beginner’s Flask course so I’m not going to explicitly explain some of the syntaxes you might see in the following sections, except it has to do with GraphQL which is what this article is all about in the first place.

models.py: As I mentioned this is where we’ll add our database models, we use Sqlalchemy extensively here. Below is what our models.py file looks like:



from sqlalchemy.orm import (
    scoped_session, relationship,
    sessionmaker
)
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import *
import os

basedir = os.getcwd()
engine = create_engine(f"sqlite:///{basedir}/dev.db")
session = scoped_session(
    sessionmaker(
        autocommit=False,
        autoflush=False,
        bind=engine
    )
)
Base = declarative_base(bind=engine)
Base.query = session.query_property()


# Note class
class Notes(Base):
    __tablename__ = 'notes'
    id = Column(Integer, primary_key=True)
    title = Column(String(100))
    body = Column(Text)
    user_id = Column(Integer, ForeignKey('user.id'))
    user = relationship('User', back_populates="notes")


class User(Base):
    __tablename__ = 'user'
    id = Column(Integer, primary_key=True)
    first_name = Column(String(100))
    last_name = Column(String(100))
    email = Column(String(100))
    password = Column(String(200))
    notes = relationship('Notes', back_populates="user")

Pretty basic models, we have a User class to represent our user table and one for the Notes table. I’m using SQLite here, but you can use whatever database you want to make this work.

Schema.py: This is the fun part, here is where we use Graphene to create graphql schemas for our server. This schema defines how queries should be written to the server, and what kinds of data can be requested from the server. An example is to define a query for all notes in the database, and would be as follows:



type User {
    name: String!
    email: String!
    password: String!
    notes: [Notes!] @relation
}

type Notes {
    title: String!
    body: String!
    author: User! @relation
}

type Query {
    allNotes: [Notes!]!
}

This is what a raw or native graphql schema looks like and this defines primitive types, namely: Notes (which represents Note objects from the database), User (which represents User objects from the database) as well as a query called allNotes to get all notes from the Notes table.

If you don’t understand this syntax please refer to the Graphql docs. We won’t however be writing native schema, there’s a rather easier way to do this with graphene by generating these “types” (Notes and User as depicted above), directly from our models, this is made possible by graphene-sqlalchemy which basically serializes our sqlalchemy models into a format Graphene can work with in order to create schemas like the one in the image above.

Let’s see how we can achieve this:



from models import (
    User as UserModel, Notes as NotesModel,
    session
)
import graphene
from graphene_sqlalchemy import (
    SQLAlchemyConnectionField,
    SQLAlchemyObjectType
)
from extensions import bcrypt
from typing import Optional

# types
class User(SQLAlchemyObjectType):
    class Meta:
        model = UserModel


class Notes(SQLAlchemyObjectType):
    class Meta:
        model = NotesModel

Here we import the required classes from graphene-sqlalchemy as well as our models, we then create a class (which subclasses SQLAlchemyObjectType) to represent each of the models. These new classes will be used throughout our schema to create query and mutation schemas. A query is used to retrieve information and is in essence sent as a GET request, mutations are used to write to the database, so they carry information and are sent as POSTs or PUTs.

Let’s see how we might define a mutation to help with registration. Usually, a mutation in native form looks something like this:

Here we have a mutation “createUser” that takes in name, email, and password as string arguments, and returns a user type which can then be further queried. Let's see how we can implement this in graphene. So after declaring our types with graphene-sqlalchemy in the previous step add the following lines to define the createUser mutation.



# registeration
class createUser(graphene.Mutation):
    class Arguments:
        first_name = graphene.String()
        last_name = graphene.String()
        email = graphene.String()
        password = graphene.String()
    ok = graphene.Boolean()
    user = graphene.Field(User)

    def mutate(root, info, first_name, last_name, email, password):
        new_user = UserModel(
            first_name=first_name,
            last_name=last_name,
            email=email,
            password=str(
                bcrypt.generate_password_hash(password),
                'utf-8'
            )
        )
        session.add(new_user)
        session.commit()
        ok = True
        return createUser(ok=ok, user=new_user)

As observed we simply subclass graphene.Mutation which is used to define mutations, and create another class called “Arguments” inside of createUser to hold arguments for our mutation. The mutation also declares its return types, ok(a boolean type) and user(which is of type User, as we declared earlier on with our models).

This is followed by a method called “mutate” that handles the request by creating a user object(with the models directly this time not the serialized user type) and uses sqlalchemy session to commit it to the database.

Lastly, we return an instance of createUser along with the status of the request with the ok variable and the newly created user object. The mutate method takes in the root and info as positional arguments. These are passed down from the Mutate class, we need them to process our queries correctly; they basically hold useful information about the query as well as its context.

Once a request is sent the mutation creates the new user and returns a response. We’ll add a couple more mutations and queries. As follows:

Add a new note: This schema represents a mutation query to add a new note



# add new note
class addNote(graphene.Mutation):
    class Arguments:
        title = graphene.String()
        body = graphene.String()
    ok = graphene.Boolean()
    note = graphene.Field(Notes)

    def mutate(root, info, title, body):
        uid = info.context['uid']
        # find user based on token payload
        user = session.query(UserModel).filter_by(email=uid).first()
        new_note = NotesModel(
            title=title,
            body=body,
            user=user
        )
        session.add(new_note)
        session.commit()
        ok = True
        return addNote(ok=ok, note=new_note)

Update an existing note: ```python

update existing note

class updateNote(graphene.Mutation):
class Arguments:
note_id = graphene.Int()
title = graphene.String()
body = graphene.String()
ok = graphene.Boolean()
note = graphene.Field(Notes)

def mutate(root, info, note_id, title: Optional[str]=None, body: Optional[str]=None):
    # find note object
    note = session.query(NotesModel).filter_by(id=note_id).first()
    if not title:
        note.body = body
    elif not body:
        note.title = title
    else:
        note.title = title
        note.body = body
    session.commit()
    ok = True
    note = note
    return updateNote(ok=ok, note=note)

- **Delete a Note** :

```python


# delete note
class deleteNote(graphene.Mutation):
    class Arguments:
        id = graphene.Int()
    ok = graphene.Boolean()
    note = graphene.Field(Notes)

    def mutate(root, info, id):
        note = session.query(NotesModel).filter_by(id=id).first()
        session.delete(note)
        ok = True
        note = note
        session.commit()
        return deleteNote(ok=ok, note=note)

Before moving on to GET queries, one final thing we must do after defining mutation classes is to mount the instances of each of our mutation classes as query fields so that they can be used to query our server - using the ObjectType class from graphene. It’s a generic type that’s used to define queries, mutations just have to be defined using the Mutation class first as seen above before declaring them as fields as we will now do below:




class PostAuthMutation(graphene.ObjectType):
    addNote = addNote.Field()
    updateNote = updateNote.Field()
    deleteNote = deleteNote.Field()


class PreAuthMutation(graphene.ObjectType):
    create_user = createUser.Field()

I’m making two classes because I’ll be creating a pair of schemas for logged in/authorized users and non-authorized users. Here, I add the mutations that are accessible by authorized users in PostAuthMutation and define them as fields using the Field() method on each one of them.

Queries: Queries to request for data from the server are simply called “queries”; these can be defined using the “ObjectType” class. Multiple queries can be defined in a single class with multiple resolver functions to handle each one if need be.



class Query(graphene.ObjectType):
    # find single note
    findNote = graphene.Field(Notes, id=graphene.Int())
    # get all notes by user
    user_notes = graphene.List(Notes)

    def resolve_user_notes(root, info):
        # find user with uid from token
        uid = info.context['uid']
        user = session.query(UserModel).filter_by(email=uid).first()
        return user.notes

    def resolve_findNote(root, info, id):
        return session.query(NotesModel).filter_by(id=id).first()

ObjectTypes are allowed to describe their fields, and this particular query has two fields described. FindNote by Id, and user_notes which represents an array of all notes by a particular user.
Observe that each field is described by a native graphene type; Field for a single value field and List to represent a field with an array of values. Each one takes the data-type for each field as its first argument. The findNote query for instance is defined as one that expects a Note-type and a keyword parameter which is what is used by the resolver to find the data.

After describing our fields we add resolver methods to handle the request. There is a naming convention for our methods and it's usually of the format - “resolver_”. This is how graphene knows which function belongs to what field. I’ll define one more query for non-authorized users.



class PreAuthQuery(graphene.ObjectType):
    all_users = graphene.List(User)

    def resolve_all_users(root, info):
        return session.query(UserModel).all()

Lastly, we’ll define two schemas, one for authorized requests and the other for non-authorized requests.



auth_required_schema = graphene.Schema(query=Query, mutation=PostAuthMutation)
schema = graphene.Schema(query=PreAuthQuery, mutation=PreAuthMutation)

extensions.py: This contains instances of some important extensions/libraries used in this project. They are used throughout the application.



from flask_bcrypt import Bcrypt
from flask_graphql_auth import GraphQLAuth
from flask_jwt_extended import JWTManager

bcrypt = Bcrypt()
auth = GraphQLAuth()
jwt = JWTManager()

data.py: I use this file to run the command that creates the database and the tables defined in the models.py file.



from models import (
    session, Base
)

# create tables
Base.metadata.create_all()

run.py: here’s where we add the command to run our flask server, to run the app we’ll simply run this file:



from core import app
import json

if __name__ == "__main__":
    app.run(debug=True)

core/init.py: Finally let’s talk about the actual server code, there’s quite a number of important things going on here. But the majority of what is being done here is regular flask setup. This is also where we’ll use flask-graphql and add the schemas we declared from schema.py to our graphql endpoints. To begin we’ll import the required dependencies, instantiate our flask app, add its configuration and pass in the flask app instance to the extensions that need it



from flask import Flask, request, jsonify
from flask_graphql import GraphQLView
from extensions import bcrypt, auth, jwt
from schema import auth_required_schema, schema
from dotenv import load_dotenv
from flask_jwt_extended import (
    create_access_token,
    create_refresh_token, get_jwt_identity,
    jwt_required
)
import os
from models import User, session

load_dotenv()  # loads environment variable from .env file

app = Flask(__name__)
app.config['SECRET_KEY'] = os.getenv('secret')
app.config['JWT_SECRET_KEY'] = os.getenv('jwtsecret')

bcrypt.init_app(app)
auth.init_app(app)
jwt.init_app(app)

Next, we define a couple of endpoints, two graphql endpoints, one for
Authorized requests and the other for non-authorized requests, as well as conventional REST-style login endpoint to create auth tokens.



@app.route('/')
def index():
    return "Go to /graphql"


@app.route('/login', methods=['POST'])
def login():
    # fetch login credentials
    data = request.get_json(force=True)
    # find user
    user = session.query(User).filter_by(email=data['email']).first()
    if not user:
        return {
            "ok":True,
            "message": "User with email not found"
        }, 404
    if bcrypt.check_password_hash(user.password, data['password']):
        token = create_access_token(identity=data['email'])
        return jsonify(access_token=token)
    return {
        "ok":True,
        "message": "Incorrect password"
    }, 401

Here we have two endpoints, one to tell the user what route the graphql server can be accessed on and the other for login. This login route is a REST endpoint and takes in JSON to log in a user and returns a token as JSON as well, this token is then used to send requests to the protected graphql endpoint - by adding it to headers of the request. Let’s see how we can use Flask-graphql to define GraphQL endpoints.



def graphql():
    view = GraphQLView.as_view(
        'graphql',
        schema=auth_required_schema,
        graphiql=True,
        get_context=lambda: {
            'session': session,
            'request':request,
            'uid': get_jwt_identity()
        }
    )
    return jwt_required(view)


app.add_url_rule(
    '/graphql',
    view_func=graphql()
)

app.add_url_rule(
    '/graphq',
    view_func=GraphQLView.as_view(
        'graphq',
        schema=schema,
        graphiql=True
    )
)

I use the flask app’s add_url_rule method to create new routes; tantamount to using the @app.route decorator, Flask also provides this method, this way you can have your handlers as standalone functions perhaps even in separate files.
The first thing we have here is the handler for the /graphql route, and in there we use the GraphQLView.as_view() method to add our schema from schema.py and specify graphiql=True, this allows the server to render an interface to write graphql queries in and test them with ease. Also, note the get_context attribute, it's important because we use it to pass important values, like the user’s identity from the token and some other important things like db session - onto each request. If you observe in our mutations we used this ‘uid’ to get the user object that's currently logged in, get_context passes the data we give it onto the info parameter on our queries.

Hopefully, that’s clear enough, now let’s run our app! First, we need to run data.py so that it creates our database and tables as defined by models.py. To do this we use the data.py file, simply run it from the cmd or terminal using :

python data.py

Next, we’ll run the app using run.py, you should now see your server logs as usual. To test visit localhost:5000/graphq which is accessible without authorization, here is where we’ll create a new user account. On this page, you’ll find two panes. The left one is where you write your graphql queries and here, we’ll create a user as follows:

As expected we declared createUser to take in those arguments, and return the status along with the newly created user object, which can also be sub-queried.

Let’s login with localhost:5000/login, via postman or curl or any other means preferred, I have a postman browser extension and that's what I’m going to be using.

Next, we can go to localhost:5000/graphql with this token in the headers. If you try to open this route without the token you’ll get this :

As such I added the token from the login request to headers from my browser via a browser plugin called ModHeader; you don’t have to test this from the browser, you can do it from Postman or any other API testing tool you prefer. From here we can then write mutations to add a note, update notes or even delete notes, or queries to fetch all notes by the user currently signed in as an example :

Of Course, we get an empty array since we haven’t added anything, we can add a new note as follows:

So that's how to set-up a simple graphql server in python using Flask, and Graphene, and that wasn’t so bad now was it?. But what if there was an easier way to get our server up and running. In the next phase of this article, I’ll be showing you how to set up a GraphQL server without actually writing backend code, or bothering about setting up a server from scratch. The next part of this article shows you how to setup a GraphQL server using Fauna’s GraphQL API.

Serverless GraphQL APIs With Fauna

So first off some introduction, before we jump right in. It’s only fair that I give Fauna a proper introduction seeing as it's about to make our lives a whole lot easier, as we will soon get to see.

Serverless and Fauna

Fauna is a serverless database service, that handles all optimization and maintenance tasks so that developers don’t have to bother about them and can focus on developing their apps and shipping to market faster.

Then again what is serverless; so serverless doesn’t actually mean “NO SERVERS”, to simply put it - what serverless means instead is that you can get things working without necessarily having to set things up from scratch, for example, some apps that use serverless concept don’t have a backend service written from scratch, they instead employ the use of cloud functions which are, technically scripts written on cloud platforms to handle necessary tasks like login, registration, serving data, etc - all without having to set up a server from scratch.

Where does Fauna fit into all of this, you ask?. Well usually, when we build servers we need to provision our server with a database, and when we do that it's usually a running instance of our database server on the same machine that our server is running on or at least on the same network. With serverless technology like Fauna, we can shift that workload to the cloud and focus on actually writing our auth systems, implementing business logic for our app, etc. Fauna also manages things like, maintenance and scaling which are usually causes for concern with systems that use conventional databases.

That’s it for the intro, if you’re interested in getting more info about Fauna and its features check the docs here. Let’s get started with building our GraphQL API the serverless way with GraphQL.

Hands On With Fauna

Requirements

Fauna Account: That’s right, that’s all you need folks; an account with Fauna is all you need for this session, so click here to go to the sign-up page.

Creating a Fauna Database

Login to your Fauna Account once you have created an account. Once on the dashboard, you should see a button to create a new database, click on that and you should see a little form to fill in the name of the database, that resembles the one below:

I call mine “graphqlbyexample” but you can choose to call yours whatever you please, also ignore the pre-populate with demo data option we don’t need that for this demonstration. Click Save and you should be brought to a new screen as shown below:

Adding a GraphQL Schema To Fauna

In order to get our GraphQL server up and running, Fauna allows us to upload our own graphql schema, on the page we’re currently on you should see a GraphQL option; select that and it’ll prompt you to upload a schema file. This file usually contains raw graphQL schema and is saved with either the .gql or .graphql file extension. Let’s create our schema and upload it to Fauna to spin up our server.

Let’s create that file, create a new file anywhere you like, I’m creating it in the same directory as our previous app, because it has no impact on it, I’m also calling it schema.gql in schema.gql we’ll add the following:



type User {
    name: String!
    email: String!
    password: String!
    notes: [Notes!] @relation
}

type Notes {
    title: String!
    body: String!
    author: User! @relation
}

Here we simply define our data types in tandem to our two tables (Notes, and User). Save this and go back to that page to upload this schema.gql that we just created. Once that’s done Fauna will process that and take us to a new page - our GraphQL API playground!!

We have literally created a graphql server by simply uploading that really simple schema to Fauna, and to highlight some of the really cool feats that Fauna has, observe:

Fauna automatically generates collections for us, If you notice we didn’t create any collection (translates to Tables, if you’re only familiar with relational databases - Fauna is a NoSQL database and collections are technically the same as tables, and documents as to rows in tables; check out the docs for more info). If we go to the collections options and click on that we’d see the tables that were auto-generated on our behalf, courtesy of the schema file that we uploaded.

Fauna automatically creates indexes on our behalf: head over to the Indexes option and see what indexes have been created on behalf of the API. Fauna is a document-oriented database and doesn’t have primary keys or foreign-keys as you’d have in relational databases for search and index purposes, instead, we create indexes in Fauna to help with data retrieval, find out more about indexes here.

Fauna automatically generates graphql queries and mutations as well as API Docs on our behalf: this one’s my personal favorite and I can’t seem to get over just how efficient Fauna does this. Fauna is able to intelligently generate some queries that it thinks you might want in your newly created API. Head over back to the GraphQL option and click on the “Docs” tab to open up the Docs on the playground.

As you can see we have two queries and a handful of mutations already auto-generated (even though we didn’t add them to our schema file), you can click on each one in the docs to see the details. Fauna’s thoughtful enough to help us create some boilerplate queries and mutations without us asking or having to hard code it in. Thank you Fauna.

Now without stalling any further, let’s run some tests!

Testing Our Server

Let's test out some of these queries and mutations from the playground, we can also use our server outside of the playground, by the way, it is a fully functional GraphQL server, after all, so we will look at how to do that as well

Testing From The Playground

We’ll test our first off by creating a new user, with the predefined createUser mutation as follows:

If we go to the collections options and choose User, we should have our newly created entry (document aka row) in our User collection.

Let’s also create a new note and associate it with a user as the author via its document ref id, which is a special ID generated by Fauna for all documents for the sake of references like this much like a key in relational tables. To find the ID for the user we just created simply navigate to the collection and from the list of documents you should see the option(a copy Icon) to copy Ref ID:

Once you have this you can create a new note and associate it as follows:

Let’s make a query this time, this time to get data from the database. Currently, we can fetch users by ID or fetch a note by its ID. Let's see that in action :

Yes you must have been thinking it, what if we wanted to fetch info of all users, currently, we can’t do that because Fauna didn’t generate that automatically for us, but we can update our schema so let’s add our custom query to our schema.gql file, as follows, note that this is an update to the file so don’t clear everything in the file out just add this to it:

Once you’ve added this save the file and click on the update schema option on the playground to upload the file again, it should take a few seconds to update, once it's done we’ll be able to use our newly created query, as follows:

Please don’t forget that as opposed to having all the info about users served (namely: name, email, password) we can choose what fields we want, cause yeah - it’s GraphQL !!, and not just that it's Fauna’s GraphQL so feel free to specify more fields if you want this is just for demo purposes so i only specified the name field to get all names of all users, and as you can observe the result is an array as clearly defined by the schema we just added.

Testing From Without the Playground - Using Python (requests library)

Now that we’ve seen that our API works from the playground lets see how we can actually use this from an application outside the playground environment, using python’s request library so if you don’t have it installed kindly install it using pip as follows:

pip install requests

Before we write any code we need to get our API key from Fauna which is what will help us communicate with our API from outside the playground. Head over to security on your dashboard and on the keys tab select the option to create a new key, it should bring up a form like this:

Leave the database option as the current one, change the role of the key from admin to the server and then save. It’ll generate for you a new key secret that you must copy and save somewhere safe, as an environment variable most probably.

For this I’m going to create a simple script to demonstrate, so add a new file call it whatever you wish - I’m calling mine test.py to your current working directory or anywhere you wish. In this file we’ll add the following:



import requests
import os

url = "https://graphql.fauna.com/graphql"

# create a request to fetch user by ID

# create query
query = """
    {
        findUserByID(id: 287471031836213761)
        {
            email
        }
    }
"""
token = os.getenv('FAUNA_SECRET')
# set headers 
headers = {"Authorization": f"Bearer {token}"}

Here we add a couple of imports, including the requests library which we use to send the requests, as well as the os module used here to load our environment variables which is where I stored the Fauna secret key we got from the previous step.

Note the URL where the request is to be sent, this is gotten from the Fauna GraphQL playground here:

Next, we create a query which is to be sent this example shows a simple fetch query to find a user by id (which is one of the automatically generated queries from Fauna), we then retrieve the key from the environment variable and store it in a variable called a token, and create a dictionary to represent out headers, this is, after all, an HTTP request so we can set headers here, and in fact, we have to because Fauna will look for our secret key from the headers of our request.

The concluding part of the code features how we use the request library to create the request, and is shown as follows:



get = requests.post(
    url=url,
    json={'query': query},
    headers=headers
)

if get.status_code == 200:
    print(get.json())
else:
    print("Error sending request..")

We create a request object and check to see if the request went through via its status_code and print the response from the server if it went well otherwise we print an error message lets run test.py and see what it returns:

Eureka! Now that it works, we can confirm that our API works off the playground as well so long as we communicate correctly with our secret key.

Conclusion

In this article, we’ve learned a lot about GraphQL - by example! now haven’t we?. We covered creating GraphQL servers from scratch and looked at creating servers right from Fauna without having to do much work, we also saw some of the awesome, cool perks that come with using the serverless system that Fauna provides, we went on to further see how we could test our servers and validate that they work.

Hopefully, this was worth your time, hope it taught you a thing or two about GraphQL, Serverless, Fauna, and Flask!. I would love to write more articles like this one, so be sure to leave positive remarks to encourage me, or even leave suggestions, if you feel like I left something out or perhaps if there was something you’d want to see me work on in a future article, please do leave a comment.

You can reach out to me on Twitter @Curiouspaul2 for further inquiries. Thank you!

Coveed: Help to mitigate stress on the medical infrastructure.

Curious Paul — Sat, 02 Jan 2021 23:59:05 +0000

What I built

Coveed - a tool that attempts to assist in the fight against the ongoing covid-19 pandemic by lessening the workload of health care workers. It does this by helping manage patients whose cases might not be as severe.

Category Submission:

Program for the People (Covid-19)

App Link

https://coveed-3t5mj.ondigitalocean.app/

Screenshots

Description

Coveed is a tool, that helps health workers monitor the health status of covid19 patients while allowing patients to create health profiles that health workers rely on for review and medical recommendations/advice. It also features, an emergency failsafe for instances where patients' health deteriorates.

Who can use Coveed

Tested patients (with minimal symptoms) who wish to self-isolate.
People who suspect that they have been infected, and are experiencing mild symptoms.

How it Works

A user signs up and he gets to add his symptoms on a daily basis to the app, and the app records that data over the space of two weeks.
The data is then sent to a review staging area. where a certified medical practitioner (MP) can review the progress of the patient based on his/her medical history. The MP can recommend that the patient stays on the app for an extra two weeks in isolation or schedule a test for the patient, and can as well flag a patient for an emergency.
While a patient is on the app the patient can willingly contact emergency and will consent to have his location revealed to health agencies, and be picked up to a proper isolation center if he observes that he's unstable.

Benefits of Coveed

It eases the tension on the medical system since lots of cases can be addressed remotely
Lowers the chances of front-liners in this war against Covid19 - getting infected
More cases can be brought under the radar, lots of people here in Nigeria, are either afraid to go for tests or ignorant, with this, we can keep an eye on them.

Link to Source Code

https://github.com/rinwaowuogba/coveed

Permissive License

MIT License

Background

I saw a problem that needed fixing, and thought I might devote mysef to fixing it. Helping to reduce the strain on the medical infrastructure is crucial if the fight against Covid-19 is to be won. Events in Italy made it ever moreso clear why the need for a revolutionary approach towards treating pandemic victims was necessary.

How I built it

I used DigitalOcean's App platform to deploy a react app. The process was very straightforward, I set some simple presets like app region, environmental variables, pricing plan, and the app was live in a matter of minutes.

I learned about using a YAML file to define an app's specifications while trying to set up the "Deploy to DigitalOcean" button. That was new to me.

DEV Community: Curious Paul

Build a Product Review Tool For Telegram Bot Using Appsmith

Prerequisites

Overview of the Tool

Adding Datasources

getReviews API

send_review API

Connect Datasources To Widgets

Integrate With The Telegram Bot

Conclusion

Adding Two-Factor Authentication Layer To Appsmith Using TypingDNA

What is TypingDNA?

Table of Contents

Getting Started With TypingDNA

Pre-requisites

Building A Backend Server Using Flask and Heroku

Building The Typing Biometrics Form

Deploying To Heroku

Creating A Heroku Application

Interfacing With Appsmith

Adding Two-Factor Authentication Modal

Implementing Form Handlers On Appsmith

Adding a protected page

Testing

Conclusion

Building An Inventory Tool Using Appsmith and HarperDB

Table of Contents

Setting Up A HarperDB Database

Adding Data To The Table

Building The Management Tool Using Appsmith

Populating The Table

Building The Inventory Form

Updating A Product

Conclusion

Making The Earth Greener With Project Gaia

Overview

How We Built Gaia

Submission Category:

Link to Code

Screenshots/demo

Collaborators

Building A Meme Generator using Appsmith

Pre-Requisites

Building The Interface on Appsmith

Integrating With HumorApi

Building Internal Tools Using Appsmith, Flask And Heroku

Table of Contents

Pre-Requisites

Building And Deploying A Flask API

Deploying To Heroku

Building The Management Tool Using Appsmith

Building The Form

Fetching Data From The API

Add A New Product

Edit A Product

Delete A Product

Conclusion

Building A Product Management Tool Using Appsmith and FaunaDB

Table of Contents

Setting Up A FaunaDB Database

Generating An API Key

Building The Management Tool Using Appsmith

Populating The Table

Building The Form

Updating A Product

Conclusion

How to Create Simple Versioning In your Database Using Fauna's Temporality Feature

What is temporality ?

Creating and configuring the database

Fetching an API key

Building the “versioning” middle-ware

Pre-Requisites

The “At” Command

The “Event” Command

The versioning tool

Conclusion

Building An E-commerce Telegram Bot Using Python and Fauna.

WHAT TELEGRAM-BUSINESS CAN DO

CUSTOMER FEATURES:

BUSINESS OWNER FEATURES: