Installing Flask

Listing 8-1 demonstrates how to install Flask using the command, pip install flask. Note that the command downloads the necessary components, extracts them, and then runs the setup for each. In this case, we see Flask is composed of several components including Werkzeug, MarkupSafe, and Jinja2. We will learn more about some of these in the “Flask Primer” section.

Installing Flask-Script

Listing 8-2 demonstrates how to install Flask-Script using the command, pip install flask-script. Note that in this case, we see the installation checking for prerequisites and their versions.

Installing Flask-Bootstrap

Listing 8-3 demonstrates how to install Flask-Bootstrap using the command, pip install flask-bootstrap. Once again, we see the installation checking for prerequisites and their versions as well as installation of dependent components.

Installing Flask-WTF

Listing 8-4 demonstrates how to install Flask-WTF using the command, pip install flask-wtf.

Installing WTForms

The following demonstrates how to install WTForms using the command, pip install WTforms. In this case, the installation is simple because we only need the one package.

You should also have the MySQL Connector/Python 8.0.5 or later database connector installed. If you do not, download it from https://dev.mysql.com/downloads/connector/python/ and install it. If you have multiple versions of Python installed, be sure to install it in all Python environments you want to use. Otherwise, you may see an error like the following when starting the code.

Pip also can be used to install MySQL Connector/Python. The following shows how to use PIP to install the connector.

If you installed MySQL Connector/Python manually or from source, you also may need to install Protobuf. You can use pip to install it as shown in the following.

Now that our computer is setup, let’s take a crash course on Flask and its associated extensions.

Flask-Script

Flask-Script enables scripting in Flask applications by adding a command-line parser (manifested as manager) that you can use to link to functions you’ve written. This is enabled by decorating the function with @manager.command. The best way to understand what this does for us is through an example.

The following is a basic, raw Flask application that does nothing. It’s not even a “hello, world” example because nothing is shown and there are no web pages hosted—it’s just the raw Flask application.

Note the app.run() call. This is called the server startup and is executed when we load the script using the Python interpreter. When we run this code, all we see is the default message from Flask as shown in the following. Note that we don’t have any way to see help as there are no such options. We also see that the code launches using defaults for the web server (which we can change in code if we desire). For example, we can change the port that the server is listening.

With Flask-Script , we add not only a help option but options to control the server. The following code shows how easy it is to add the statements to enable Flask-Script. The new statements are highlighted in bold.

When this code is run, we can see there are additional options available. Note that the documentation string (immediately following the method definition) is shown as the help text for the command added.

Note that we see the command line arguments (commands) we added, hello_world, but we also see two new ones supplied by Flask-Script; shell and runserver. You must choose one of these commands when launching the server. The shell command allows you to use the code in a Python interpreter or similar tool and the runserver executes the code starting the web server.

Not only can we get help about the commands and options, Flask-Script also provides more control over the server from the command line. In fact, we can see all the options for each command by appending the --help option as shown in the following.

Note here that we can control all manner of things about the server including the port, host, and even how it executes.

Finally, we can execute the method we’ve decorated as a command-line option as shown in the following.

Thus, Flask-Script provides some very powerful features with only a few lines of code. You’ve got to love that!

Flask-Bootstrap

Flask-Bootstrap was originally developed by Twitter for making uniform, nice-looking web clients. It is fortunate that they’ve made it a Flask extension so that everyone can take advantage of its features. Flask-Bootstrap is a framework on its own and provides even more command-line control as well as user interface components for clean, attractive web pages. It also is compatible with the newest web browsers.

The framework does its magic behind the scenes as a client library of cascading style sheets (CSS) and scripts that are invoked from the HTML templates (commonly referred to as either HTML files or template files) in Flask. We will learn more about templates in a later section. Because it is client-side, we won’t see much by initializing it in the main application. Regardless, the following shows how to add Flask-bootstrap to our application code. Here, we see we have a skeleton with Flask-Script and Flask-Bootstrap initialized and configured.

WTForms

WTForms is a component we need to support the Flask-WTF extension. It provides much of the functionality that the Flask-WTF component provides (because the Flask-WTF component is a Flask-specific wrapper for WTForms). Therefore, we need only install it as a prerequisite for Flask-WTF and we will discuss it in the context of Flask-WTF.

Flask-WTF

The Flask-WTF extension is an interesting component providing several very useful additions: most notable for our purposes integration with WTForms (a framework agnostic component) that permits the creation of form classes, and additional web security in the form of cross-site request forgery (CSRF) protection. These two features allow you to take your web application to a higher level of sophistication.

Message Flashing

There are many cool features in Flask. The creators and the creators of the Flask extensions seem to have thought of everything—even error messaging. Consider a typical web application. How do you communicate errors to the user? Do you redirect to a new page,³ issue a popup,⁴ or perhaps display the error on the page? Flask has a solution for this called message flashing.

Message flashing is accomplished using the flash() method from the Flask framework. We simply import it in the preamble of our code then when we want to display a message, we call the flash() function passing in the error message we want to see. Flask will present the error in a nicely formatted box presented at the top of the form. It doesn’t replace the form and isn’t a popup but it does allow the user to dismiss the message. You can use flash messaging to communicate errors, warnings, and even state changes to the user. Figure 8-1 shows an example of a flash message. In this example, we see two flash messages that demonstrate you can display multiple messages at the same time. Note the small X to the right of the message used to dismiss the image.

We will see a mechanism to build flash messaging into all our web pages in the next section.

Jinja2 Templates Overview

Jinja2 templates , (or templates), are used to contain any presentation logic like looping through data arrays, making decisions on what to display, and even formatting and presentation settings. If you are familiar with other web development environments, you may have seen this encapsulated in scripts or enabled through embedded scripting such as JavaScript.

Recall we rendered our web pages in our main code. This function tells Flask to read the file specified and convert the template constructs (render them) into HTML. That is, Flask will expand and compile the template constructs into HTML that the web server can present to the client.

There are several template constructs you can use to control the flow of execution, loops, and even comments. Whenever you want to use a template construct (think scripting language), you enclose it with {% %} prefix and suffix. This enables the Flask framework to recognize the construct as a template operation rather than HTML.

However, it is not unusual and quite normal to see the template constructs intermixed with HTML tags. In fact, that is exactly how you should do it. After all, the files you will create are named .html. They just happen to contain template constructs. Does that mean you can only use templates when working with Flask? No, certainly not. If you want, you can render a pure HTML file!

At first, looking at templates can be quite daunting. But it isn’t that difficult. Just look at all the lines with the {% and %} as the “code” portions.⁵ You also may see comments in the form of {# #} prefix and suffix.

If you look at the template, you will see the constructs and tags and formatted using indentation of two spaces. Indentation and whitespace in general doesn’t matter outside the tags and constructs. However, most developers will use some form of indentation to make the file easier to read. In fact, most coding guidelines require indentation.

One of the cool features of templates beyond the constructs (think code) is the ability to create a hierarchy of templates. This allows you to create a “base” template that your other templates can use. For example, you can create a boilerplate of template constructs and HTML tags so that all your web pages look the same.

Recall from our look at Flask-Bootstrap, bootstrap provides several nice formatting features. One of those features is creating a pleasant looking navigation bar. Naturally, we would want this to appear on all our web pages. We can do this by defining it in the base template and extending it in our other template (HTML) files. Let’s look at a base template for the library application. Listing 8-5 shows the base template for the library application. Line numbers have been added for ease of discussion.

Wow, there is a lot going on here! Note the first line. This tells us that we’re inheriting (extending) another template named bootstrap/base.html template. This is provided for you free when you install Flask-Bootstrap and it is this template that contains support for the bootstrap navigation bar feature. This is a very common method of building a set of HTML files for a Flask application as we will see later in this section.

Let’s start our tour with a bird’s eye view. Note that there are two “blocks” designated with {% block <> %} and {% endblock %} (lines 2, 3, 28, 30, 38, and 40). These are logical sections where we can apply formatting to the tags and constructs inside the block. In coding terms, this would be like a code block. The first block defines the title for the page. In this case, MyLibrary, which is the executable name for the library application.

The second block defines the navigation bar (think menu) for the application. Note in that section lines 5–27 define simple HTML <div> tags forming the items on the navigation bar. Of note are line 13, which specifies text to be used as the name of the application, which appears to the left of the navigation bar and acts like a “home” link. Lines 15–24 define the navigation bar items (submit buttons) for three web pages (forms). Note also the collapse keyword. This indicates it is possible to collapse the navigation bar. So, what does the navigation bar look like? Figure 8-2 shows the navigation bar for the library application in normal, collapsed, and expanded mode. The normal and collapsed mode operates based on the size of the browser window collapsing when the navigation item labels cannot be displayed. The expanded mode operates when users click on the button to the right when in collapsed mode. Cool, eh?

The last block in lines 30–39 defines the template construct and HTML tags for the flash messages. Let’s take a deeper look at this code (repeated here for convenience).

Here, we see another <div> tag that contains a button. This is the button we use to dismiss the flash message. Note that this tag is placed inside a for loop as designated with {% for ... %} and ended with {% endfor %}. In this case, we are looping over the messages returned from the get_flashed_messages() function, which is collected by the flash() function in our application code. This tells us several things: we can use loops in our templates, the template allows the display of multiple images (which we saw earlier), and templates can call functions! This is an example of the power of templates.

Finally, note the variable we defined in the for loop in line 32. This variable, message, is defined local to the block in which it appears (in this case, the for loop), and can be referenced at any point by enclosing it in {{ }}. For example, we see in line 35 we use {{ message }} inside the <div> tag, which means this text will appear on the client rendered in place by Flask. The use of variables will become more important when we discuss how to build user interfaces with templates.

Template Language Constructs

The Jinja2 template features are many and a complete discussion of all features is beyond the scope of this book. However, it is handy to have a quick reference for the major constructs of Jinja2. The following present some of the commonly used constructs including some that we discovered in the last section (for completeness). Each is presented with a short example of how the construct would appear in a template. Feel free to refer to this section when exploring the library application later in the chapter or when writing your own Flask applications.

HTML Files Using Templates

Now we are ready to see how to manifest the field classes we defined in our form classes. Let’s begin the discussion with a walkthrough of how to present data for the publisher data in the library application. We begin with the form class and the field classes defined to the view function, which renders the template and finally the template itself.

Recall, that the form class is where we define one or more form fields. We will use these field class instances to access the data in our view functions and in the template. Listing 8-6 show the form class (without database access).

Note that the form class creates three fields: one for the publisher name (name), one for the city in which the publisher is based (city), and another for the publisher URL (url). We also see two submit fields (buttons): one for creating new publisher data (create_button), and one for deleting publisher data (del_button). We also have a hidden field for the publisher id.

We pass the form data to the template when it is rendered after instantiating it in the view function. Listing 8-7 shows the view function for the publisher data. Here, we instantiate the publisher form class first then pass it to the template.

Note here that we see the routes we’ve defined for the view. Note also that we have set the methods for requests to include both GET and POST. We can check to see if the request is a POST (submission of data). It is in this condition that we can retrieve data from the form class instance and save it to the database. We’ll look at that a bit more when we add database capabilities.

Finally, note that we instantiate an instance of the publisher form class (form) and later pass that as a parameter to the render_template("publisher.html", form=form) call. In this case, we now render the publisher.html template stored in the templates folder.

Ok, now we have our form class and view function. The focus now is what happens when we render the HTML template file. Listing 8-8 shows the HTML file (template) for the publisher data.

Note that the template begins with extending (inheriting) the base.html template file that we discussed earlier. We see a block defining the title and another block defining the page content. In that block, we see how to define the fields on the page referencing the field class instances from the form class instance (form). Indeed, note that we reference the label of the field as well as the data. The label is defined when you declare that the field class and the data is where the values are stored. When we want to populate a form (GET) we set the data element to the value and when we want to read the data (POST), we reference the data element.

Note that we also added the CSRF token for security, rendered the hidden fields with the form.hidden_tag() function, and included the submit fields conditionally by including the delete submit field (del_button).

Whew! That’s how Flask works to present a web page. Once you’re used to it, it is a nifty way to separate several layers of functionality and make it easy to get data from the user or present it to the user.

Now, let’s look at how to build custom error handlers into our application and later how to redirect control in our application to the correct view functions.

Not Found (404) Errors

To handle 404 (not found) errors, we create a view function with the special error handler routing function, which renders the HTML file. Flask will automatically direct all not found error conditions to this view. The following shows the view function for the 404 not found error handler. As you can see, it is simple.

The associated error handler HTML code is in the file named 404.html as shown in the following. Note that we inherit it from the base.html file so the resulting web page looks the same as any other in the application complete with the menu from the bootstrap component. Note that we also can define the text for the error message and a title. Feel free to embellish your own error handlers to make things more interesting for your users.⁷

Application (500) Errors

To handle 500 (application) errors, follow the same pattern as before. The following is the error handler for the application errors.

The associated error handler HTML code is in the file named 500.html as shown in the following. Note that we inherit it from the base.html file so the resulting web page looks the same as any other in the application complete with the menu from the bootstrap component.

Creating these basic error handlers is highly recommended for all Flask applications. You may find the application error handler most helpful when developing your application. You can even augment the code to provide debug information to be displayed in the web page.

Author Form Class

The author form is very simple and requires only three fields: one to store the primary key for the row using a HiddenField field class, one for the first name, and one for the last name. Both name fields use a TextField field class. Validation for the name fields set both to required (hint: they’re defined as NOT NULL in the database table) along with minimal and maximum length checks. We also need two SubmitField field classes: one for Add and another for Delete. Recall, we will control programmatically the delete button in the template. Listing 8-11 shows the AuthorForm form class.

Publisher Form Class

The publisher form also is very simple and requires only four fields: one to store the primary key for the row using a HiddenField field class, one for the publisher name, one for the publisher city of origin, and another for the URL for the publisher. All three visible fields use a TextField field class. Validation for the name and city fields set both to required (hint: they’re defined as NOT NULL in the database table) along with minimal and maximum length checks. The URL field as no validators because it is an optional field for the data (it can be NULL in the database table). We also see the two SubmitFields() for the Add and Delete buttons. Listing 8-12 shows the PublisherForm form class.

Book Form Class

Before we discuss the form class for the book detail view, there is a small issue that needs to be overcome. There is a commonly known catch when using the SelectField() and SelectMultipleField() field classes. The prevalidation code can present some unusual results when validated if there is no default selected or if you set the default programmatically. To overcome these limitations, we can create our own derived field class and override the prevalidation code. Listing 8-13 shows the code used to create custom versions of these field classes to overcome the limitation. You will need to place these in your code if you want to use either of these field classes.

Note that in each case, we override the pre_validate() and process_formdata() methods allowing us to ignore prevalidation and make it easier to update the values. Now let’s look at the code for the book form class. Listing 8-14 shows the code for the BookForm form class. Note that we use the new field classes for the authors and publisher fields. We also see the two SubmitFields() for the Add and Delete buttons.

List Form Class

To save duplicate code, we will create a simple form class that we can use to create a simple list of rows in the form of an HTML table. The code for this is very simple because all the presentation code will be in the template file. The following is the code for the ListForm form class.

Now that we’ve seen all the form classes for the library application, we now examine the associated view functions.

Author Template

The author template creates a form for viewing, editing, and creating author data. As such, we give the page a legend, host the hidden field (for the auto increment primary key), and place the label and form field on the form for each of the fields. We keep it simple by listing the fields vertically (but you can use any format you want). We also set the size of the fields using the form fields default function. For example, to set the size for the first name field to 75 characters, we use form.firstname(size=75). Finally, we see the logic to turn on the delete button if it is defined (we will see how to disable it later). Listing 8-19 shows the completed template for the author data (named author.html).

Publisher Template

The publisher template creates a form for viewing, editing, and creating publisher data. As such, we give the page a legend, host the hidden field (for the auto increment primary key), and place the label and form field on the form for each of the fields. We keep it simple by listing the fields vertically (but you can use any format you want). We also set the size of the fields. Finally, we see the logic to turn on the delete button if it is defined (we will see how to disable it later). Listing 8-20 shows the completed template for the publisher data (named publisher.html).

Book Template

The book template is a bit more complex. We start out with a legend and the hidden tag, which stores the ISBN for the current data, then build the form listing the labels and the fields vertically setting the size of the fields as we go. So far, this is similar to how we built the author and publisher templates.

Things get a bit more interesting when we try to set the field size for the select fields. In this case, we need to use the style parameter passing in the width parameter using units in pixels. This is one of the very few nuances of Flask templates that can be a bit tricky because the size parameter doesn’t apply to the select fields (but now you know how to get around it). As with the previous templates, we see the logic to turn on the delete button if it is defined (we will see how to disable it later).

After that, we see some additional logic for working with notes. The notes feature allows users to add notes to the book after it has been created. Thus, we need to both show any existing notes and provide a means to add a new note, but only when the page is used for update operations. You can see how this is done near the bottom of the file.

Listing 8-21 shows the completed template for the publisher data (named book.html). Take some time to read through the file until you are confident you understand how it works.

List Template

Despite the rather complex view function for the list feature, the template for the list view is rather straightforward. We simply add the New button (submit field) at the top, provide a legend, and then format the table using the columns array from the view function. We then build the HTML table using the rows also provided from the view function. Listing 8-22 shows the completed template for the list data (named list.html).

Other Templates

Recall, there are three other templates that we’ve seen previously that we will be using: the 404 and 500 error handlers (404.html, 500.html) as described in the section, “Error Handlers” and the base template (base.html) as shown in Listing 8-5.