[Django] Django project folder layout structure

source: http://tian-yi.me/django-project-folder-layout-structure.html

Django project folder layout structure

I have failed to find much mention about project folder layout structure in Django's documentation. From the tutorial on the official Django site, it points out that a project should have the following structure:

    myproject
    |-- manage.py
    |-- myproject
    |   |-- __init__.py
    |   |-- settings.py
    |   |-- urls.py
    |   `-- wsgi.py
    `-- app_one
    |   |-- __init__.py
    |   |-- models.py
    |   |-- views.py
    |   `-- urls.py
    `-- app_two
        |-- __init__.py
        |-- models.py
        |-- views.py
        `-- urls.py

Static files

Ok, this looks pretty good, but where should I place my static files? In the documentation, it says using thecollectstatic management command to gather all the static files from your static file storage and copy them into the directory given by STATIC_ROOT. It sounds super easy, doesn't it? So I placed all my static files in a folder calledstatic within each app, then I ran the collectstatic command, Django did put all the static files into theSTATIC_ROOT folder, but it did not create folder for each app, instead, it mixed all the static files. So I did a bit research, found out that I needed to create another folder in the static folder within each app(e.g.,static/app_one), it can be called whatever you like, just it would be easier to name it the same as your app's name. Then I ran the collectstatic command again, all the static files had been placed in its app folder in theSTATIC_ROOT folder. Maybe it was just me being dumb, I should have thought about this, but if you do a bit googling, you will see this actually confuses many Django novices. Anyway, now it all looks good, but what if there are some common static files in each app? Like jQuery and such? I created a folder calledcommon_static/common in the project folder, and place all the common static files in it, so it will create acommon folder in the STATIC_ROOT folder. By default, collectstatic command will look for files within static/subdirectories of apps in your INSTALLED_APPS. But the common_static/common is not in any apps, so we need to add it to STATICFILES_DIRS in settings.py.

Like this:

    from os.path import dirname, join

    STATICFILES_DIRS = (
        join(dirname(dirname(__file__)), "common_static"),
    )

So when you need to reference the static file, you can use {{ STATIC_URL }} in the Django template. For example, if I need a file called app_one.js in app_one, I can reference it in my template like {{ STATIC_URL }}app_one/app_one.js. So this way you will never need to worry about relative path or absolute path when you reference your static files. There is one more problem though, do I need to run collectstatic command every time I modify a file in development? The answer is no, there is a trick you can use during development. First, set the variable DEBUG insettings.py to True, then in your main urls.py add something like this:

    from django.contrib.staticfiles.urls import staticfiles_urlpatterns

    if settings.DEBUG:
        urlpatterns += staticfiles_urlpatterns()

So you do not need to run collectstatic during development, Django knows where to look for those files. But you need to remember to change DEBUG to False when you deploy your project, and run collectstatic as well. Then make your Apache or Nginx to server the STATIC_ROOT folder.

Template files

Now, let's have a look at how we should structure our template folders. Same as for static files, Django by default will look for template files within template/ subdirectories of app in your INSTALLED_APPS. You do not need to run something like collectstatic or such, Django will go through each folder to find the template you required. In a way, it's like Django putting all the files from each template folder into one folder. So there will be conflict if you have some templates from different apps having same names. We can create a folder structure to avoid this. It's similar to the folder structure for the static files. We need to create another folder inside the template folder in each app. It's like what we did for static files, we should name the folder the same name as the app. For example:app_one/template/app_one/. Normally you would want all the different components on the site using the same theme, therefore some common templates need to be shared between different apps. I had this base.html need to be inherited by other pages on the site, so I placed this file into a main project template folder. Because this template folder is not in any apps, so we need to put its path in to TEMPLATE_DIRS in settings.py. In the views, when you need refer to a certain template, you can do something like this:

Need a template from app_one:

    loader.get_template('app_one/index.html')

Need a template from app_two:

    loader.get_template('app_two/index.html')

Need a project base template:

    loader.get_template('base.html')

A TEMPLATE_DIRS example:

    from os.path import dirname, join

    TEMPLATE_DIRS = (
        join(dirname(dirname(__file__)), "templates"),
    )

So after all the changes, a proper Django project folder structure should look like this:

    myproject
    |-- manage.py
    |-- static
    |-- templates
    |-- common_static/common/
    |-- myproject
    |   |-- __init__.py
    |   |-- settings.py
    |   |-- urls.py
    |   `-- wsgi.py
    `-- app_one
    |   |-- __init__.py
    |   |-- models.py
    |   |-- views.py
    |   |-- urls.py
    |   |-- static/app_one/
    |   `-- templates/app_one/
    `-- app_two
        |-- __init__.py
        |-- models.py
        |-- views.py
        |-- urls.py
        |-- static/app_two/
        `-- templates/app_two/

Jinuine Blog

이 블로그 검색