Building an AJAX-based CRUD app in Flask

Full stack development is no easy task, and even a simple application can involve a lot of moving parts. To help you get to grips with some of the processes and requirements involved, this is the final article in a three-part series that takes us through building a basic web application.

In our case, it’s a basic app that curates details on a selection of retro video games. We’ve been using Postgres as our back-end database, and to interact with it, we’ve been using Flask, which is a lightweight framework for building web apps, supporting the Python programming language.

In our last two tutorials on Postgres and building a basic Flask app, we started building a create-read-update-delete (CRUD) application. This is the basic model for many web apps that handle records, backed by an online relational database. We’ll be building on the work in those first two tutorials, which you can find here and here. In the final tutorial of the series, we'll flesh out our vintage video games app RetroNerds to cover all the CRUD features, using AJAX to make managing our database records a smoother process.

Our rudimentary app from the last tutorial used Python to render data from the database directly in HTML. As our application gets more complex, this will become less and less viable. Instead, we need a framework to handle those different CRUD functions. Flask is based on a web application design pattern known as model-view-controller (MVC), and we'll use this as the basis for our app.

Think of MVC as having three layers. At the back is the ‘model’, which is the back-end database. We spent the first tutorial in this series setting up the database and using SQL to access it. In the second, we learned how to interact with it in the object-oriented format that Python understands, using a tool called SQLAlchemy.

The second part of the MVC framework is the controller. Think of this as a switchboard that directs different requests from the user. When we ask to create, read, update, or delete a record, it’s the controller that finds the right function to do it and then interacts with the model.

The controller does this using routes that point to different functions. We defined the most basic route - the one that gets triggered when you visit the RetroNerds index page - in the last tutorial. Our next task is to define routes covering all the CRUD functions.

The final part of the MVC is the view. This is the display that the user sees. It shows us our data and allows us to make requests. MVC views use templates to hold and update data dynamically.

We'll begin by importing Flask's template rendering library, along with several others that we'll need during this tutorial. Working with the previous tutorial's source code, update line one with an expanded list of packages:

Now replace the def index(): function in the app.route('/') section with this simplified code:

Instead of looping through the results of our database query and generating the HTML manually, it renders the query inside a template called index.html. That template must sit inside the project file in a directory called templates. Create the directory, and put this in the index.html template:

The key part here is inside the <ul> unordered list. Flask uses a templating language called Jinja, which we use to loop over the games in the query results that we passed from our index function. It puts each of the games' titles in a list element (<a>).

Stop your Flask app in the terminal if it's still running, and enter export FLASK_ENV=development in Linux or $env:FLASK_ENV = "development"

in Windows Powershell. This puts Flask into development mode so that you can see any changes to your code without restarting the app. It also displays useful debug data if your app fails. Now run your app with python3 retronerds.py and visit the URL it gives you. Your game titles should now have been added to your template.

However, we still need to read the rest of the details for each record, and we need to create and delete new records. We'll use a single form for all these tasks. We'll insert the code for this form below the // form comment in our file:

The embedded JavaScript generates the years for which we're tracking games dynamically in our dropdown.

Note that the form has a hidden class, which we defined using the internal CSS code at the start of our document. Any element with that class is invisible, meaning we can turn it on and off at will.

We'll set up the basic framework to turn our multi-purpose form on and off inside the <script> tabs we created in our // Javascript section.

We'll start by defining constants reflecting the elements in our form, beginning with the form itself. This makes them easier to manipulate later:

Now we'll create a function to hide and show the form. We can give it a button to create, update, or delete a record, making it a multi-purpose form. We display and hide the appropriate buttons based on a task parameter that we pass to this function. If we're creating a form, then we'll ensure it's cleared and that only the createButton is showing (along with the cancel button, which is always displayed). Note that this form also recognises a read task. That's because we’re also using this form to display game records, giving the viewer the chance to update them.

Finally, we'll create a function to hide our form.

Notice that our cancel button already has an onclick event handler to execute this function.

Now we'll use this to display the form with the necessary controls to create a record. We'll do this with a link that will open the form. This goes in the HTML section of the page, just underneath the // controls section:

When the user clicks on this, the form will appear with a create button.

Creating

To manipulate our records, including creating them, we'll use a technique called asynchronous JavaScript and XML (AJAX). This helps us to organise our requests in the browser, send them to the server, and then update the display on the browser side.

The advantage of doing it this way is that we won't have to query the database after creating, updating, or reading a record. We won't have to reload the entire web page after these actions, either. This creates a smoother experience for the user, who won’t have to wait while the page refreshes. Instead, things will look more seamless and instant, as new information will appear on the page straight away.

To make this happen, we'll update specific records in the browser using a JavaScript API called Fetch. This sends and retrieves records from a server using JSON, which is a standard format for exchanging data between web apps and browsers.

We trigger the function when our createButton is clicked. Although it's a form submission button, we'll grab control of it so that our JavaScript can define what it does.

Now we use fetch to capture the form input and encode it in JSON format:

fetch points to what looks like a folder on the server called /games/create/. This is another application route, which tells the server that we want to create a file. Before we write that code, we'll finish this function by defining what we want to do with the response from the server.

The fetch API represents the server's response as an object called a ‘promise’, which handles all the timeout and callback housekeeping you'd normally have to do when dealing synchronously with the server. It's called response, and we can turn it into a usable format by passing it through a json method.

From there, we create an <a> tag in JavaScript, populate it with the response's title property, and give it the ID that the server sent back. That gives us enough information to list it dynamically on the page as a new game, all without reloading the page:

Now we must write the code for the controller on the server. We'll define this as a route, much like our existing index page route, only longer:

Notice how this route mirrors the action defined in our form, meaning that it will be invoked on the server side by the fetch command. First, this route's function uses the request library that we imported at the beginning to gather values from the form's various fields. Then it creates an instance of the Game class and populates it with that data.

That will be the record that SQLAlchemy's object-relational manager writes to the server. It commits that transaction to the database, unless there's an error, in which case it rolls back that transaction. If all goes well, it returns the title of the game as written and the ID of the new record in the database to the browser.

Reading

We've included all the buttons we need to create, update, and delete records, but what about reading them? To handle this, we'll set an event handler on each of the games listed on our page. When we click on a game, its details will appear in our form, and we'll get the opportunity to update its records. We can do this because we already used Jinja to set the ID of each title's <a> tag as its game's ID in the database. Here's the code to iterate over the items in the list:

When we click on a list item containing an <a> tag with an ID, it triggers the readgame function. This is why it was so important to include an id attribute and an event handler when adding the new game that we created to our list; it had to be clickable, otherwise we'd end up with a list of clickable ones and a non-interactive one at the end.

Next, add the function to read game data to your JavaScript section:

It's a pointer to another route, which queries the controller on the server and inserts its response into the relevant fields of the form. It also changes the data-id attributes of both the updateButton and the deleteButton to the ID of the game that we clicked on, which it got from the id attribute of the game's <a> tag. This is crucial for updating or deleting a game, because we have to send its ID to the controller route on the server.

Updating

When we click the update button, we’ll send the form's contents to the controller, which will use the update route to look up the corresponding record in the database and then replace its data with the new data that we entered into the form. Here's the JavaScript function to send that update:

We kick off the function when the update button is clicked. Notice that this time, the route in our fetch command has the game's ID inserted into it so that the server knows which game it is updating. When the response comes back, we also update the game's title on the page in case that was one of the fields that we changed. We do that by searching for the <a> tag with the game's ID and then changing its text.

Here's the corresponding controller function on the server:

This code uses the familiar block structure for error handling. It extracts the form data sent to it in JSON format and then uses the game ID in the route to look up the appropriate record in the database, extracting that information into an instance of the Game class. It then replaces all of those properties with the new ones from the JSON file and uses SQLAlchemy to update the record with the new data. Finally, it returns the title for the view to update its list with.

Deleting

All that remains now is the delete part of our CRUD application, which is relatively simple. On the client side, this goes into our JavaScript section:

Note the use of the DELETE method rather than POST. Once again, this function sends the game's ID in the request. When the server confirms that it's deleted the game in its JSON response, the function deletes the <li> element containing the game's <a> tag.

All it needs to send back in the JSON response is confirmation.

There are lots more tweaks that a competent developer should make to this app before putting it into production. Field input validation, displaying error messages, ordering the games alphabetically, and styling it properly with CSS are just a few items on the to-do list. Not to mention tackling security properly with a well-structured environment variable system so that you don't store secrets in the source code.

Nevertheless, this demonstrates the basic functionality of an AJAX-enabled CRUD application. It has the bare bones of a web app that you could use to build more sophisticated controllers and more complex views.

The source code below, listed in full, would be a useful place to begin tinkering and making your own improvements. Things to consider include splitting up the CRUD interactions into multiple views, so that you can have separate screens to read files that you don’t want to update. That would also enable you to support different classes of user that don’t have update or delete privileges, which would be another thing on the to-do list for a production-ready application.

Other enhancements would include adding more data for the games (including images) and also enhancing the underlying database schema to use multiple tables with joins. Having separate tables for publisher and genre would stop you having to store the same data in multiple fields, and also makes it easier to list games that span different genres and have multiple publishers..

There’s a lot more to learn about full stack development, and there are lots of different ways to code an application even as simple as this one. Hopefully, though, this will have given you a taste of what is a difficult but ultimately rewarding activity.

retronerds.py

index.html