Step 1 : Analysis and first prototype¶
The fictive application we are going to write is a website of a Local Exchange Trade System group (LETS). The members of that site would register the products and services they want to sell or to buy. The goal is to connect the providers and the customers. We don't care whether and how transactions actually occur, neither about history... we just help them to find each other.
Products : one row for every product or service. We keep it simple and just record the designation for our products. We don't even record a price.
Members : the people who use this site to register their offers and demands. For each member we record their contact data such as place and email.
An Offer is when a given member declares that they want to sell a given product.
A Demand is when a given member declares that they want to buy a given product.
Every member is located in a given Place. And in a future version we want to add filtering on offers and demands limited to the place.
Here is a graphical representation of the database structure:
You shoud do such diagrams interactively, together with the customer. Above picture has been realized using graphviz. You might prefer Dia which renders it as follows:
There are many methodologies for visualizing a database model (UML, IDEF1X), and above style is just our favourite because it is so simple, intuitive and useful. The basic rules are:
Every node on the diagram represents a database model.
Every arrow on the diagram represents a ForeignKey. We prefer to use the word pointer instead of ForeignKey when talking with a customer because that's more intuitive.
We display the name of a pointer only if it differs from the model it points to. For example the arrow from Offer to Product is a FK field called product, defined on the Offer model. We do not display the name product on our diagram because that would be a waste of place.
The colors of this diagram are a convention for grouping the models into three "data categories":
red is for master data (i.e. relatively stable data)
yellow is for moving data (i.e. data which changes relatively often)
blue is for configuration data (i.e. data which is rather in background and accessible only to site managers)
Writing a prototype¶
With above information you should be ready to write a "first draft" or "prototype" or "proof of concept".
For this tutorial we wrote that prototype for you. The code and the docs are in Lino LETS repository.
Note the difference between "code" and "specs". The code directory contains
runnable Python code and application-specific configuration files. A copy of
this would be needed on a production site. The specs is a Sphinx
documentation tree and contains mainly
.rst files. These are not needed
on a production site. Their first purpose is to contain tests.
To try the examples in this tutorial on your own computer, you must install our code.
Assuming that you have installed your Lino developer environment, open a terminal and say:
$ cd ~/lino $ mkdir repositories $ cd repositories $ git clone https://gitlab.com/lino-framework/lets.git $ pip install -e lets/
If you have installed a Lino contributor environment, you can run the demo by saying:
$ cd ~/lino/repositories/lets/lets_demo/projects/letsdemo $ python manage.py prep $ python manage.py runserver
For storing what the customer calls "members", we decided to use the standard
lino.modlib.users. But we extend it:
we change the verbose model name from "User" to "Member"
we add a field
place, which is a pointer to our table of places.
Note the detail_layout attributes of certain tables. They define the layout of the detail window for these database models (a detail window is what Lino opens when the user double-clicks on a given row).
The detail window of a Product should show the data fields and two slave tables, one showing the the offers and another with the demands for this product.
Here is the application code that produces the picture on the right
detail_layout = """ id name OffersByProduct DemandsByProduct """
The dashboard shows the ActiveProducts table. The definition of that table is
get_dashboard_items method is defined
Here are some screenshots.