Django + Unpoly - The tutorial - Part 1

1st: 15 July 2023 • Last Updated: 15 July 2023 • 4 min read

Why?

I mentioned here where and why I opted for Unpoly. TL;DR: most of the systems I build are CRUDs. Unpoly make them feel like SPAs. That’s it.

How?

Unpoly is a JS lib, not a framework. It serves as a “middleman” from the rendered page you have on your browser and the response you get from interacting with it. This middleman takes the response, extracts and replace in the current page (that rendered one) the piece(s) of HTML you instructed it to replace.

Let’s begin

Create a basic Django project

django-admin startproject django_unpoly

Configure a templates folder

In your settings.py file, change the TEMPLATES section to add a templates folder on the root of the new project (remember to create the folder on the project):

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [os.path.join(BASE_DIR, 'templates')],  <------ Here!
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Create a base template

In the templates folder, create a base.html file and add the base HTML for your project:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="format-detection" content="telephone=no">
    <title>Django + Unpoly</title>
  </head>
  <body>
    {% block content %}{% endblock %}
  </body>
</html>

Create a static folder

Create a static folder in the root of the project (beside the templates folder. To summarize, our project structure should look like this:

├── django_unpoly
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── static
└── templates
└── base.html

Make sure our Django project runs

Start your Django project and make sure everything is working fine:

python manage.py runserver

The output should be similar to this:

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s):
 admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
July 08, 2023 - 14:33:35
Django version 4.2.2, using settings 'django_unpoly.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Check on your browser for the default page Django creates for new projects.

Install Unpoly

As I mentioned, Unpoly is just a JS lib. Download it from Unpoly’s website: https://unpoly.com/install/download and add it to your main template.  Extract the downloaded zip, and move the content to the static folder you created. Update the base.html file to refer to the new extracted files:

{% load static %}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="format-detection" content="telephone=no">
    <title>Django + Unpoly</title>

    <link rel="stylesheet" href="{% static 'css/unpoly.css' %}">  <------ Here!
    <script src="{% static 'js/unpoly.js' %}" defer></script>     <------ Here!
  </head>
  <body>
    {% block content %}{% endblock %}
  </body>
</html>

And you’re done. No build steps, no transpilers, no CI changes.

Note that there are other ways to install it: https://unpoly.com/install#methods

Next steps

In the next article, we’ll be using Unpoly do make some magic.