Sm0ke

Posted on Jan 14, 2020 • Edited on Oct 14, 2021

Django Dashboard Atlantis - Learn by coding simple tasks

#python #django #opensource #appseed

Hello Coders,

This article aims to help students and beginners to learn programming by updating an open-source admin panel coded in Django Framework. Anyone that follows this challenge will achieve a few things:

Accommodate with Git / Django Framework
Accommodate with a production-ready starter: Django Atlantis
Build a Python project using a Virtual environment
Change the title of an existing page
Create a new page
List defined users, by using the Django shell

Thanks for reading! - Content provided by App Generator.

The web app used in this article is published on Github, under the MIT license is coded with a basic set of features on top of a beautiful UI Kit:

SQLite, Django native ORM
Modular code-base
Session-Based Authentication (login, register)
Forms validation
UI Kit: Atlantis Dark Dashboard provided by ThemeKita

What is Django (web framework)

Django is an open-source web application framework written in Python. A framework means a collection of modules and helpers that make development easier. They are logically grouped together and allow you to create web applications by reusing stuff, instead of writing all from scratch.

Useful Django Resources:

Django - official website and docs
Reddit/r/Django - a super active Reddit community
Django - related content provided by the (popular) Full-Stack-Python platform

Clone the source code

As mentioned before, the app is published on Github and we can easily grab the sources by downloading the zip from the project page or using a terminal and git command tool to clone the sources:

$ git clone https://github.com/app-generator/django-dashboard-atlantis-dark.git
$ cd django-dashboard-atlantis-dark

The Code Structure

After we have the source code locally, let's take a moment to analyze the structure. Django projects, by default, are modular and quite easy to understand and update. Our project is not an exception and the code-base is split into three modules:

Core module - used to handle the static assets (JS, CSS, images) and global configuration
Authentication module - handles the login & users registration
App module - manage all other actions: serve app pages when users are authenticated and redirect to the login page otherwise. The relevant files are listed in this simple chart:

 # Source code:
 # https://github.com/app-generator/django-dashboard-atlantis-dark

 <django-dashboard-atlantis-dark>
     |
     |-- requirements.txt # project dependencies 
     |-- manage.py        # app bootstrapper 
     |
     |-- <core>
     |      | 
     |      |---- settings.py # global settings 
     |      |---- urls.py     # define the routing rules  
     |      |
     |      |---- <static>    # used for assets (js, css, images)  
     |      |---- <templates> # HTML templates 
     |                |       
     |                |-- layouts, includes, pages
     |
     | 
     |-- <authentication> 
     |      | 
     |      |---- views.py # manage Login, registration pages
     |      |---- urls.py  # Auth routing rules (login, register)
     |      |---- forms.py # Define auth forms  
     |
     | 
     |-- <app> 
     |      | 
     |      |---- views.py  # load dashboard pages
     |      |---- urls.py   # Define the routing rules 
     |      |---- models.py # Define the User model, used by authentication
     |
     |-- ******************************************************************

Have questions regarding the structure? AMA in the comments.

Build the project

Python / Django projects, usually are build from sources and to do that we need to install the project dependencies listed in the requirements.txt. We can install the dependencies in two ways:

Using the global Python environment, to install the project dependencies is now always a good practice based on the fact that we might have conflicts between versions used in other applications
Using a Virtual environment - most of the time, the recommended way that helps us to execute and build the app using Python sandbox. All modules required by the app are installed inside the Virtual ENV and the risk to have conflicts with modules used by other Python apps disappears.

To activate a Virtual ENV, and install the modules we need to type a few simple commands in the terminal:

$ # Make sure you are inside the project
$ cd django-dashboard-atlantis-dark
$
$ # Virtualenv modules installation (Unix based systems)
$ virtualenv --no-site-packages env
$ source env/bin/activate
$
$ # Virtualenv modules installation (Windows based systems)
$ # virtualenv --no-site-packages env
$ # .\env\Scripts\activate
$ 
$ # Install modules
$ pip3 install -r requirements.txt

If all goes well, we can go to the next phase:

Start the Web App

To have a usable Django web app, we need to set up the database, before starting. This can be easily done with only two simple commands:

$ # makemigrations sub-command will generate the necessary SQL code
$ python manage.py makemigrations
$
$ # Migrate sub-command will create the SQLite database and tables
$ python manage.py migrate

If all goes well, we can start the app and visit the UI in the browser by typing in the console:

$ # Start the application (development mode)
$ python manage.py runserver # default port 8000
$
$ # Start the app - custom port 
$ # python manage.py runserver 0.0.0.0:<your_port>
$
$ # Access the web app in browser: http://127.0.0.1:8000/

By default, there is no default user defined in the application, and we need to create one. As mentioned in the first part of the article, the app comes with authentication screens for login and registration.

Registration Page

After user creation, we can access the login page and authenticate:

After login, we should see the web app menus and the default dashboard page:

Update the page title

In this Django project, pages are rendered using composition between a master page and a real page that extends the skeleton with specific data. For instance, the index page extends the master page default.html

Code for master page

<head>

   <meta http-equiv="X-UA-Compatible" content="IE=edge" />
   <title>
    Django Dashboard Atlantis - { % block title % }{ % endblock % } | AppSeed 
   </title>

</head>
<body data-background-color="dark">
    { % include 'includes/navigation.html' % }

    { % include 'includes/sidenav.html' % }

    <div class="main-panel">
        <div class="content">

            { % content % }{ % content % }

        </div>

    { % include 'includes/footer.html' % }

    </div>

</body>
</html>

When a new page extends another page, the specific content should be defined between corespondent blocks, as we can see for the index page:

{% extends "layouts/default.html" %}

{% block title %} Dashboard {% endblock title %}

{ % block content % }

   <H1> Specific Content injected into the master page </H1>

{ % endblock content % }

In order to change the page title, we need to update the text inside the title block:

{% extends "layouts/default.html" %}

{% block title %} New Title {% endblock title %}

...

Create a new page

The application, if the current user is authenticated serve the pages from the directory pages . To make easier this task, the project comes with a black page that we can use as a skeleton to add new pages:

Black page path : root / core / templates / pages

The page content:

{% extends "layouts/default.html" %}

{% block title %} Dashboard {% endblock title %}

<!-- Specific CSS goes HERE -->
{% block stylesheets %}{% endblock stylesheets %}

{% block content %}

    <!-- (Almost) A blank page -->
    <h3>
    Add content here
    </h3>

{% endblock content %}

<!-- Specific JS goes HERE -->
{% block javascripts %}{% endblock javascripts %}

In order to create a new page, just save this template as new-page.html, update the content as bellow, save and access the new page in the browser: http://localhost:8000/new-page.html

{% extends "layouts/default.html" %}

{% block title %} My Page Title {% endblock title %}

<!-- Specific CSS goes HERE -->
{% block stylesheets %}{% endblock stylesheets %}

{% block content %}

    <!-- Your content here -->
    <h3>
    This is my content rendered by my new page. 
    </h3>

{% endblock content %}

<!-- Specific JS goes HERE -->
{% block javascripts %}{% endblock javascripts %}

List users using the console

Django offers a convenient way to test the application structures, database information, and methods defined or used by the application: the Django shell

To start the Django shell we need to use the shell sub-command

$ # Start the Django shell
$ python manage.py shell

If all goes well we should see this output :

>>> Python 3.7.2 (tags/v3.7.2:9a3ffc0492, Dec 23 2018, 22:20:52) [MSC v.1916 32 bit (Intel)] on win32
>>> Type "help", "copyright", "credits" or "license" for more information.
>>> (InteractiveConsole)
>>>

From this point, we can interact with our project data and methods by this shell interface. For listing all users registered in the application we need to import the Users model, where all users are saved, and make a query using the Django native ORM:

>>> from django.contrib.auth.models import User
>>> User.objects.all()
<QuerySet [<User: test>]>
>>> User.objects.all()[0].id
1
>>> User.objects.all()[0].username
`test`