Creating Your Own Django Apps

You might have noticed that there is no real program code in your project so far. There is a settings file with configuration information, an almost empty URLs file, and a command-line utility that launches a website that doesn’t do much.

This is because to create a functioning Django website, you need to create Django applications. A Django application (or app for short) is where the work gets done. Apps are one of Django’s killer features. Not only do they allow you to add functionality to a Django project without interfering with other parts of the project, but apps are designed to be portable so you can use one app in multiple projects.

So, let’s create our first custom Django app. Our social club website needs an events calendar to show upcoming events for the club, so we’re creating a Django app called events.

Fire up your Python virtual environment, switch into the \myclub_root folder and run the command:

python manage.py startapp events

This is what your command shell output should look like:

(env_myclub) ...> cd myclub_root
(env_myclub) ...\myclub_root> python manage.py startapp events
(env_myclub) ...\myclub_root>

Once you have created your app, you must tell Django to install it into your project. This is easy to do—inside your settings.py file is a list named INSTALLED_APPS. This list contains all the apps installed in your Django project. Django comes with a few apps pre-installed, we just have to add your new events app to the list (change in bold):

1 INSTALLED_APPS = [
2     'events.apps.EventsConfig',
3     'django.contrib.admin',
4     # more apps
5 ]

Inside every app, Django creates a file, apps.py, containing a configuration class named after your app. Here, the class is named EventsConfig. To register our app with Django, we need to point to the EventsConfig class—which is what we are doing in line 2 of our modified INSTALLED_APPS list.

If you were wondering, EventsConfig contains a single configuration option by default—the name of the app (“events”).

Line Numbering in Code Examples

Throughout the book, I use line numbering to make it easier for you to follow along with the explanations.

As I often use code snippets from your application files, the line numbering in the example is not the same as the line numbering in the actual source code file.

Now let’s look inside the \myclub_root folder to see what Django has created for us:

\events
    \migrations
    __init__.py
    admin.py
    apps.py
    models.py
    tests.py
    views.py

• The migrations folder is where Django stores migrations, or changes to your database. There’s nothing in here you need to worry about right now.
• __init__.py tells Python that your events app is a package.
• admin.py is where you register your app’s models with the Django admin application.
• apps.py is a configuration file common to all Django apps
• models.py is the module containing the models for your app.
• tests.py contains test procedures that run when testing your app.
• views.py is the module containing the views for your app.

Now we have a complete picture of a Django project, we can also answer the question from earlier in the chapter: “well, if it’s not a view, where does it go?”

When you have code that isn’t a view, you create a new Python module (.py file) inside your app and put related functions and classes inside the file. Note the emphasis on related. If you have a bunch of functions that provide database management utilities, for example, put them all in one file. Functions and classes not related to database management should go in another file. You should also try to be descriptive in naming modules—after all, it’s more sensible to put your database functions in a file called db_utils.py than a file called monkeys.py…

When creating new modules for your Django project, you should also consider scope. While adding custom modules to apps is far more common (and more portable), you can have project-level modules (e.g., Django’s manage.py) and site-level modules. In the latter case, your custom modules should go in the same folder as your settings.py file.

The last couple of points might seem blindingly obvious, but it’s important to understand that, while Django has a default logic to its structure, nothing is cast in stone. Django is flexible and allows you to expand and change your project structure to suit the logic of your web application.

Now we have a thorough understanding of the structure of Django’s projects and apps, the next obvious question, given we are building web applications is “how do we navigate a Django project?”

To answer this question, we need to check out the final piece of the Django big picture puzzle—URL configurations.