The Planets Tutorial will introduce Flask-Diamond by demonstrating a simple web application that manages Planets and Satellites in a database. When you are done with this tutorial, you will understand a powerful pattern for using Flask-Diamond to develop applications. This tutorial assumes you have already installed the System Requirements.
The Planets Tutorial consists of two parts:
Simply follow the tutorial and we’ll install everything, then use it to demonstrate some useful principles about Flask-Diamond applications.
During the tutorial, we will accomplish the following:
The following commands will prepare you to begin the tutorial:
mkdir planets
cd planets
mkvirtualenv -a . planets
pip install Flask-Diamond ipython
flask-diamond scaffold app
For a more detailed explanation of these commands, please see the Quick Start. When you run flask-diamond scaffold app, you will be prompted to answer some questions. Give your application and module the name of planets during scaffolding. For all other questions, you can accept the default answers by pressing Enter for each question.
Now, we’ll use a special scaffold called tutorial-planets for the rest of this tutorial. The tutorial-planets scaffold places some example models and views into the application structure.
flask-diamond scaffold tutorial-planets
make test db server
open http://localhost:5000
Your web browser should now display the planets application. If you ran into problems, please review the Quick Start to ensure you have all the requirements installed and working.
The Planets application comes with two object classes:
We will use these classes to model our solar system.
The first thing to do is enter the application shell. The make shell command enters the application context, connects to the database, and starts an interactive shell that will allow us to interact with our application.
make shell
Enter the following commands to create Earth.
from planets import models
earth = models.Planet.create(name="Earth", mass=100.0)
We have provided two parameters to the Planet.create method: name and mass. These model parameters come from the Planet model class definition, which we will investigate in the next section.
Also create Earth’s lunar body, the Moon.
moon = models.Satellite.create(name="Moon", mass=25.0, planet=earth)
Take note of the additional parameter: planet. The application database now contains the Earth and the Moon.
Using a text editor, inspect the files in planets/models.
The Planet model enables us to capture the name and mass of a planet in the application database. The Satellite model is similar to the Planet model, but it also includes a foreign key relationship so that satellites may belong to planets. See Facet: Database for more about how to write model classes.
Log in to GUI
Using a web browser, connect to the application server in a new tab. If you used the default scaffolding settings, your application server is online at http://localhost:5000/.
First, log in as admin@example.com using randomly generated password. The development password can be recovered from Makefile.
Create Mars
Now that you have logged in, create a new Planet called Mars using the GUI. Choose Admin from the drop-down menu at the top of the screen. Select the Planet model from the menu. Once the Planets List View has loaded, click Create to make a new planet. Use the following values:
Create Phobos
Repeat this process to create a new Satellite using the menus.
However, you will run into trouble when you try to set the planet to Mars. To fix this, open the file models/planet.py. Add a function called __str__ within the Planet class:
def __str__(self):
return self.name
With the string representation function in place, try to create Phobos again. You will now be able to select Mars from the drop-down.
The last step in this tutorial is to look at the most important file of all, __init__.py, which controls every aspect of your application. Using a text editor, inspect the file planets/__init__.py. Flask-Diamond applications mostly follow Flask’s create_app() pattern. If you are not yet familiar with Flask applications, read Writing an Application with Flask-Diamond.
blueprints facet
Take a look at init_blueprints, which registers two blueprints that provide basic administrative functionality to your application. To add new views to your application, you will extend this function to register your own blueprints.
administration facet
Finally, look at init_administration, which adds a ModelView for Planets and Satellites. When you create new models in your application, if you wish to edit those models using the GUI, you will need to add those new models to init_administration.
To recap this tutorial, we covered the following:
These fundamental ideas are common to many applications. Of course, this tutorial is just an introduction. Each of these topics has many more readings that will help you learn to master the facets of your application.