Skip to content

Home

Jump to bottom
Val Huber edited this page Dec 13, 2020 · 45 revisions

FAB Quick Start Guide

Python Flask Application Builder (fab) creates "basic" applications for database crud operations quickly, with minimal coding. Typical fab pages can look like this:

  1. Multi-page: apps include 1 page per table
  2. Multi-table: pages include related_views for each related child table, and join in parent data
  3. Favorite field first: first-displayed field is "name", or contains "name" (configurable)
  4. Predictive joins: favorite field of each parent is shown (product name - not the foreign key product_id_)
  5. Ids last: such boring fields are not shown on lists, and at the end on other pages

This is the FAB Quick Start Guide. In about 10 minutes, we'll

  1. Install Python and FAB, and
  2. Create the application above using an existing database called Northwind (customers, orders, items, etc). The app is 52 pages, for 13 underlying tables.

Install Python Pre-reqs

To get started, you will need: Python3

  • Python
  • virtualenv - a best practice for keeping Python / libraries separate for each project. Install as described here (basically, pip install virtualenv)
  • IDE: Python works with various debuggers; here are setup instructions for two popular ones. The screen shot below is VSCode (recommended but not required for this Quick Start).

Create Sample nw project

Follow the procedure below to create a new FAB project.

1 - Create Empty Project Folder and env

First, we create an empty project folder, with a venv for dependencies.
We'll use nw for our project directory name. For more information, see the FAB docs.

mkdir nw
cd nw
virtualenv venv
# windows venv\Scripts\activate
source venv/bin/activate

Note: You can deactivate this venv, but you must reactivate using the last command above whenever you wish to work on the project again.

2 - Create Empty fab Project

Install FAB (and dependencies), and create a default empty FAB app:

pip install flask-appbuilder
flask fab create-app

You will then be prompted for the project name and your db engine type. When prompted:

  • Use the default engine
  • Name the project nw-app

You should see a structure as shown in the screen shot in the next section.

We now have a well-formed empty project. We now need to acquire and configure a database, set up SQLAlchemy ORM models.py, and define our pages with views.py.

3 - Configure Database

To get the database:

  1. Download this file, a sqlite version of Northwind.
  2. Copy it to your nw-app folder
  3. Update your nw-app/config.py file to denote this database name (illustrated below): Northwind_small.sqlite

Your project will look something like this:

fab_quick-start project

Key FAB inputs can become tedious: models.py and views.py

FAB requires that we edit 2 key files to make our "empty" project interact with the database. These can get tedious, due to per-page code required for each table / page. For more information, see here.

The following sections show how to use generators to avoid the tedious hand creation of the views.py and the models.py files.

4 - Create models.py

You must provide model classes for SQLAlchemy. That's a bit of work (13 classes in this small example), but we can automate this with sqlacodegen, like this:

cd nw-app
pip install sqlacodegen
sqlacodegen sqlite:///Northwind_small.sqlite --noviews > app/models.py

This overwrites your nw/nw-app/app/models.py module. For more information, see the sqlacodegen docs.

5 - Define views.py

Finally, we need to define some pages. That's also a bit of work to do that by hand, so let's use fab-quick-start to create the views.py file from the app/models.py file (hit enter to accept defaults when prompted):

pip install fab-quick-start
fab-quick-start run --favorites="name description" --non_favorites="id" > app/views.py

This overwrites your nw/nw-app/app/views.py file. For more information, see the FAB Quick Start Utility docs.

6 - Create Admin

The FAB system can create tables in your database for authenticating and authorizing users (tables such as ab_user, ab_user_role, etc). You create these as follows (Username: admin, Password: p):

(venv)$ export FLASK_APP=app
(venv)$ flask fab create-admin
Username [admin]:
User first name [admin]:
User last name [user]:
Email [admin@fab.org]:
Password:
Repeat for confirmation:

Ignore the error "user already exists", since the admin data was pre-loaded.

You can verify your data and admin data like this (mac/unix only):

sqlite3 Northwind_small.sqlite  # mac only
> .tables
> .schema Order
> select * from ab_user;
> select * from Territory;
> .quit

7 - Run `nw' App

You've now created a app with a dozen pages or so; run it like this:

(venv)$ # still cd'd to nw-app
(venv)$ export FLASK_APP=app
(venv)$ flask run

Start your browser here.

Login as admin, password p.

Deeper Dive

So, you’ve seen how to generate a basic app. That’s just the basic fab flow. To discover more:

  1. Explore Samples: FAB contains a number of samples you can explore. Here are setup instructions.
  2. Explore Docs: you can edit the generated views.py file for charts and many other options. The full doc is here.
Clone this wiki locally