An ultimte guide to building an order tracking dashboard with Appsmith

Appsmith is an open-source framework for developing low code dashboards, workflows, pages, and CRUD apps very quickly. Appsmith allows you to build tools with little or no code. Appsmith has more flexibility than off-the-shelf options and it’s fast to build and easy to maintain.

In this tutorial, you are going to learn how to use Appsmith to build an order tracking dashboard for an e-commerce store. The store’s order data is stored on a Firestore database, you would also see how to quickly integrate Firestore into your Appsmith dashboard and run queries from Appsmith.

Before we get started let’s go over some requirements needed to complete this tutorial:

A Firebase account with Firestore setup
Experience with Javascript is a plus but not required
Finally, you can view a demo of what you would be building here

Alright, that’s all you need. So let’s jump right in.

Setup

Before you can start using Appsmith, you need to create an account, so head over to Appsmth to create an account if you have not already done that. Alternatively, you can also deploy Appsmith on your local machine or private server instance since it’s open-source software but that’s beyond the scope of this tutorial.

You should be redirected to the dashboard after signing up. The next step is to create a new application on Appsmith.

Click the Create New button to create a new application and name it Acme Store. This takes you to an empty workspace with a sidebar. On the sidebar, you should see a navigation menu with a page. Pages are synonymous with web pages. Each page on Appsmith includes the widget, the datasources and the JS objects. in the following content, we would build the app by digging deeper into each of these items.

The Datasource

Appsmith allows you to easily integrate APIs or databases such as MongoDB, Firestore and more out of the box. You can run queries to read and write data directly from the Appsmith editor.

This tutorial integrates with a Firestore database.

💡 It is assumed that you already have an existing Firestore database set up, you can follow this guide to quickly get one running.

Configure the Datasource

On the Appsmith dashboard, click on + next to Datasources and find Firebase on the list.

The Firestore plugin requires three pieces of information to establish a connection; the database URL, the project id and the service account credentials. Follow the below instructions to set it up:

Project ID: Navigate to "Project Settings" in your Firebase console and ensure you're in the "General" tab. You'll find a "Project ID" here, copy this value into the "Project ID" field in the Firestore configuration.
Database URL: The database URL need to be formed using the Firebase project ID you found above. Enter the database URL in the following manner your-project-id.firebaseio.com
Fetching Service Account Credentials: Navigate to the “service accounts” tab in your firebase console and find a "Generate new private key" button below the code snippet. Click the button to generate a new private key to access this Firestore instance and open the JSON file downloaded. Paste the content of this file into the "Service Account Credentials" field.

After filling up the three fields as described above, click on the "Test" button to verify the configuration and click "Save".

Data Schema

Remember we’re building an application to track a record of orders. It would be nice to populate the database with some documents at this point so we can focus on integrating these records into the app moving on.

Collections hold documents. Since Firestore is a no-SQL database, it doesn't expect your documents to be fixed to a certain schema. You can structure every object of your documents as you deem fit but you still try as much as possible to keep your data uniform.

Create a new collection and call it orders to record the orders. Then you need to place some documents in the collection. Here’s the orders schema this tutorial is working with:

date: A timestamp value for when the order was placed.
shipment: A map/object that holds the shipping details for the order. it contains the address, email and phone of string types.
**items:** An array of objects/maps of the items bought. Each item contains its price, quantity and productName
**customer**: info about the customer that placed the order. Contains the name and email of the customer
status: a string label to track the status of the order

Go ahead and populate the orders collection with some document records following the above convention.

you should have something similar to this:

You also need a collection to hold the list of status you track orders with. It follows the same process as for the orders.

Create a new collection and call it labels add a document to the collection, name the document status_labels and populate it with the following fields:

**values:** an array of objects/map containing label and value properties which are both string types.

you should also have something similar to this:

Execute Queries

Now that you have fully integrated the database, you are ready to start adding some actual integrations. Appsmith allows you to create queries to fetch and update data from your datasource using the Appsmith query editor.

You can create and manage queries from the sidebar on the Appsmith dashboard. Click on the datasource you integrated earlier, on the next page, click on the “new query” button to create a new query.

Get orders

This query would fetch all the records from the orders collection.

Create a new query and name it get_orders. Click the commands dropdown and select ‘Get Documents in Collection’ since we are getting the record of documents in the orders collection. The “Collection/Document Path” should be orders. Leave the remaining fields as their default.

Run the query and you should have something similar to this in the response field:

{
  "date": {
    "seconds": 1642460400,
    "nanos": 0
  },
  "shipment": {
    "address": "lagos, nigeria",
    "phone": "+2346994948383",
    "email": "taylorswift@gmail.com"
  },
  "_ref": {
    "id": "1g3VP3gNePsYGZWNaC4k",
    "path": "orders/1g3VP3gNePsYGZWNaC4k"
  },
  "items": [
    {
      "quantity": "4",
      "price": "25000",
      "productName": "Stallion Rice"
    }
  ],
  "status": "draft",
  "customer": {
    "name": "Taylor Swift",
    "email": "taylorswift@gmail.com"
  }
}

Get status labels

This query returns the record of status labels in the database. It follows a similar process as getting all orders except this reads a document and not a collection.

Create a new query, set commands to “Get Single Document” and the path as “labels/status”.

Run the query and you should get a response similar to this:

{
  "values": [
    {
      "label": "pending",
      "value": "pending"
    },
    {
      "label": "draft",
      "value": "draft"
    }
  ],
  "_ref": {
    "id": "status",
    "path": "labels/status"
  }
}

Update order

The final query allows us to update the order directly from the dashboard, to keep this tutorial simple we’re only focusing on updating the order’s status.

Create a new query and set the command to “Update Document”. Next is the “Collection/Document Path”, set it to orders/{{orders.selectedRow._ref["id"]}}. Notice how the query extracts the current row data id from the table widget, this way, you’re able to update the selected document. But we don’t have any widgets yet, so let’s go ahead and build that next.

Run the query and firestore should return a timestamp value denoting the last update time:

{
  "lastUpdateTime": {
    "seconds": 1642981099,
    "nanos": 88277000
  }
}

The Widgets

Widgets act as the building blocks for Appsmith UI. They can be dragged from the widget pane, positioned on the canvas, and resized to fit the data they need to display. They also come with properties that can be visually edited to set their data, change their styles, and trigger actions from them.

Widget properties can be edited via the property pane which is opened using the top-right icon (Edit Widget Properties). Data from a Query can be set in a widget property by referencing the name (unique identifier) of the Query.

We’ve been going over some boring stuff all day, it’s about time we did something fun. Let’s start building out the UI for the app.

Heading

It would be nice to place a heading on the top of the app. On the sidebar toggle the widgets panel and drag the text widget onto the canvas. Then from the properties panel, change the text to “Acme Store Dashboard”. Next drag in a divider widget right under the heading.

Every other widget would be placed under the header.

Table

This would be used to display the orders in tabular form. On the sidebar toggle the widgets panel and drag the table widget onto the canvas. Then from the properties panel, delete the default columns and the default table data. Then create the date, order Id, customer and status columns.

Details panel

On the selection of each table row, we want to show more data about the order on that row in the details panel. Drag in a “container” widget and logically divide the screen portion under the heading such that the table takes up 60% and the details panel takes up 40% of the screen width.

Add another container widget in the details panel and place a text widget in it, rename the text to “Track Order”. Next, drag in a text widget for order Id and place another text widget next to it to hold the value, do the same for the customer, address, email and phone.

Place a divider before the address, email and phone fields and place a heading “Shipment” using the text widget above them.

Add another divider, an heading “Items” and drag in another table widget into the panel.

💡 You might need to resize the table in an open area of the canvas so that it fits the details panel before you can place it there. learn more about resizing a widget here

Finally, add a button to update the database with the edits. Update the button text to “Update” from the properties panel.

You’re almost done with the UI, but first, take some time to update the UI to match the image below:

Integrate Datasource

It's time to bring your implementation to life by making everything you have been implementing communicate with each other.

Display Data in Tables

The table widget can automatically loop through an array of items provided as the table data.

Set the table data from the properties pane by referencing the get all orders query.

{{get_orders.data}}

Let’s take a moment to talk about the brackets. Appsmith supports writing single line javascript from any field between the template syntax {{}}, the content within it can then point to a variable or be an evaluation.

Appsmith is reactive, that way, the get_orders value is stored immediately you tested it earlier so you don’t have to run the query for every field you need it. In the example above, the syntax refers to the data returned from the get_orders query.

💡 widgets are automatically updated whenever the data in the Query changes

After adding the table data, the columns and values are automatically populated for you with the top-level properties from the response data, but we don’t want to show that much information on the table. On the right of each icon use the eye icon to hide each column except the date customer and status.

You also need to add another column for the order id by clicking the “ADD A NEW COLUMN” button and naming it to order Id. Configure the value by clicking the “Setting” icon on the column and place the following syntax in the computed value field:

#{{currentRow._ref["id"]}}

The {{currentRow._ref["id"]}} is used to select the id from the table’s current selected row. We then place a # character is placed before each value.

Display values in the detail panel

The values displayed here would be inferred from the selected row, so it’s dynamic and shows detail for each order.

For the Order id, replace its value field with the following template syntax:

#{{orders.selectedRow._ref["id"]}}

Replace the customer value field with the following template syntax:

{{orders.selectedRow.customer}}

Replace the label text for the status with the following template syntax:

{{orders.selectedRow.status}}

For the options, you need to get the value from the query to get status labels, replace the options field of the status dropdown with the syntax below:

{{get_status_labels.data.values}}

Next is the update button. We want to keep track of the orders by updating their status using the labels you have just configured. But when you change the label from the dashboard, it doesn't reflect on the database yet.

Button widgets in Appsmith have an event handler property which can be found on the properties pane. The idea is to run the update record query each time the button is clicked, persisting the updated status in the Firestore. Select execute a query as the event select the update_order query you created earlier. Now change the label and click the update button, notice the change from your database.

Keep your data up to date

You’re almost done except that you don’t want your table to have redundant fields. Appsmith allows you to also specify callback actions to handle both success and error events. For now, we are concerned with the success callback, we can use this to fetch the current data from Firestore and Appsmith would automatically propagate the data into the widgets.

Click on the update button, then select the onSuccess callback from the onClick event handler, select execute a query as the action the select the get_orders query.

You should now have a similar dashboard to the one in the image below:

Publish your Application

The last step is to make it available for use, there are a couple of ways to do this; you can either add people to the organization where the project sits or make it generally available to the public.

Select the share button from the far right of the navbar and you should see a toggle button labelled Make the application public in the modal that pops up, toggle it and copy the generated link to start sharing your progress.

💡 Remember, the demo for this tutorial is available here

Conclusion

Congratulations! you have seen how easy it is to build a custom dashboard with little code using a WYSWYG editor. You can fully utilize this approach to build a fully functional dashboard for your enterprise and small scale e-commerce applications.

Thanks for reading, I’m Azeez Lukman and here’s a developer’s journey to building something awesome every day. Please let's meet on Twitter, LinkedIn, GitHub and anywhere else @robogeeek95.

Blog