Play with your first Lino site¶

On this page we are going to have a deeper look at what happened when you installed your Lino developer environment as described in Install your Lino developer environment.

Project directories ¶

~/lino/lino_local¶

This is your projects root, which will hold all the Lino sites on your computer. Lino project directories are not very big, and you will hopefully create many such projects and want to keep a backup of them.

~/lino/lino_local/first¶

This is the Django project directory of the first site you created in Install your Lino developer environment.

Django project directory¶: A directory that contains a runnable Django project. It contains the files necessary for that specific instance of a given Lino application.

Usually there is one Django project directory for every Lino site. (An exception to that rule is a site with multiple front ends, you may leave this for later).

The `settings.py` file ¶

Your first settings.py file should look as follows:

from lino_book.projects.min2.settings import *
SITE = Site(globals(), title="My Lino site")
DEBUG = True

Explanations:

lino_book.projects.min2 is one of the demo projects included in the Developer Guide. Actually it is the second of a series of projects documented in The Lino Minimal projects.

We import these settings directly into our global namespace using the wildcard *. This is necessary because that's how Django wants settings.
Then comes the trick that turns your Django project into a Lino application:
```
SITE = Site(globals(), ...)
```
That is, you instantiate a Site class and store this object as SITE in your Django settings. This line will automatically install default values for all required Django settings (e.g. DATABASES and LOGGING) into your global namespace.

You might add DEBUG = True or other settings of your choice after these two lines, but it is not necessary here.

There are two possibilities to override the Site attributes. The most basic way is:

from lino_book.projects.chatter.settings import *
SITE = Site(globals(), title="My Lino site", is_demo_site=False, languages="en fr")
DEBUG = True

The more explicit way is this:

from lino_book.projects.chatter.settings import *

class Site(Site):
    title = "My Lino site"
    is_demo_site = False
    languages = "en fr"

SITE = Site(globals())
DEBUG = True

This way is recommended on production sites because it allows to override methods as well. Yes, Lino saves us not only from having to define all-uppercase settings, it also adds the full power of the Puython language to your settings.py file. More about this in The local settings.py file.

The `manage.py` file ¶

The manage.py file should have the following content:

#!/usr/bin/env python
import os
import sys

if __name__ == "__main__":
    os.environ["DJANGO_SETTINGS_MODULE"] = "settings"
    from lino.core.management import execute_from_command_line
    execute_from_command_line(sys.argv)

A manage.py does two things: it sets the DJANGO_SETTINGS_MODULE environment variable and then calls Django's execute_from_command_line function.

This is plain traditional Django know-how. There are many opinions, tricks, flavors and conventions about Django's manage.py files, partly for historical reasons. Lino does not add any tricks to the manage.py file, so you can use your own flavour if you prefer.

Loading initial data into your database ¶

Next we create your database and populate it with some demo content. With a Lino application this is easier than with a plain Django project, it is just one command to type:

$ python manage.py prep

The pm prep command is a custom django-admin command provided by Lino. It is just a thin wrapper that calls initdb with the application's Demo fixtures as argument. It will ask you:

INFO Started manage.py prep (using settings) --> PID 28463
We are going to flush your database (.../default.db).
Are you sure (y/n) ?

If you answer "y" here, then Lino will delete everything in the given database and replace it with its "factory default" demo data. Yes, that's what we want. So go on and type y.

The output that follows should look like this:

>>> shell("python manage.py prep --noinput")
... 
`initdb std demo demo2` started on database .../hello/default.db.
Operations to perform:
  Synchronize unmigrated apps: about, bootstrap3, cal, checkdata, contacts, countries, export_excel, extjs, gfks, jinja, lino, office, printing, staticfiles, system, users, xl
  Apply all migrations: contenttypes, sessions
Synchronizing apps without migrations:
  Creating tables...
    Creating table system_siteconfig
    Creating table users_user
    Creating table users_authority
    Creating table countries_country
    Creating table countries_place
    Creating table contacts_uploadvcardfile
    Creating table contacts_partner
    Creating table contacts_person
    Creating table contacts_companytype
    Creating table contacts_company
    Creating table contacts_roletype
    Creating table contacts_role
    Creating table gfks_helptext
    Creating table checkdata_message
    Creating table cal_remotecalendar
    Creating table cal_room
    Creating table cal_eventtype
    Creating table cal_guestrole
    Creating table cal_calendar
    Creating table cal_subscription
    Creating table cal_task
    Creating table cal_eventpolicy
    Creating table cal_entryrepeater
    Creating table cal_recurrentevent
    Creating table cal_event
    Creating table cal_guest
    Running deferred SQL...
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying sessions.0001_initial... OK
Loading data from .../lino_xl/lib/contacts/fixtures/std.py
Loading data from .../lino/modlib/gfks/fixtures/std.py
Loading data from .../lino_xl/lib/cal/fixtures/std.py
Loading data from .../lino/modlib/users/fixtures/demo.py
Loading data from .../lino_xl/lib/countries/fixtures/demo.py
Loading data from .../lino_xl/lib/contacts/fixtures/demo.py
Loading data from .../lino_xl/lib/cal/fixtures/demo.py
Loading data from .../lino/modlib/users/fixtures/demo2.py
Loading data from .../lino_xl/lib/cal/fixtures/demo2.py
Installed ... object(s) from ... fixture(s)

Lino applications make abundant use of what we call Python fixtures in order to have a rich set of "demo data". We will come back to this in The initdb command.

Visualizing database content from the command-line ¶

The runserver command starts a web server and lets you interact with the database through the web interface. But Django also offers a shell interface. We will come back to this later, for the moment just try the following.

You can visualize the content of your database from the command-line without starting a web server using Lino's show command. For example to see the list of countries, you can write:

>>> shell("python manage.py show countries.Countries")
... 
============================= ==========
 Designation                   ISO code
----------------------------- ----------
 Bangladesh                    BD
 Belgium                       BE
 Congo (Democratic Republic)   CD
 Estonia                       EE
 France                        FR
 Germany                       DE
 Maroc                         MA
 Netherlands                   NL
 Russia                        RU
============================= ==========

Exercises ¶

You can now play around by changing things in your project.

In your settings.py file, replace lino_book.projects.min2 by lino_book.projects.polly. Run python manage.py prep followed by python manage.py runserver. Log in and play around.
Same as previous, but with lino_book.projects.chatter
Write three descriptions (e.g. in LibreOffice .odt format), one for each of the applications you just saw: what it can do, what are the features, what functionalities are missing. Use screenshots. Use a language that can be understood by non-programmers. Send these documents to your mentor.
Read the documentation about the following Site attributes and try to change them:
- is_demo_site
- languages

Checkpoint ¶

If you follow an internship, you should now have a meeting with your mentor and show him what you learned so far. You'll get a badge to certify your progress.