Come ridisegnare l’Admin di Django con Bootstrap

Il sito di amministrazione di Django è fantastico — completo di funzionalità, facile da usare, sicuro per progettazione, solido come una roccia… e un po’ brutto, il che può essere un aspetto negativo quando si desidera integrarlo con l’aspetto e il feel del resto del tuo sito web. Occupiamoci di questo.

Se Non è Rotto…

Immagina di aver appena prototipato un’app web con Django e Vue.js. Per una vasta gamma di casi, utilizzare l’amministratore di Django per scopi di back office così com’è, e persino consegnarlo al tuo cliente dopo aver impostato le autorizzazioni in modo appropriato, va benissimo. Dopotutto, funziona perfettamente e può essere pesantemente personalizzato con gli strumenti interni per coprire molte situazioni.

Quindi ancora, perché preoccuparsi?

Motivi per Modificare l’Aspetto e il Feel dell’Amministratore

Tuttavia, ci sono numerosi motivi validi per fare un passo avanti nell’integrazione:

Branding: non c’è nulla di sbagliato nel voler il nome e i colori della tua azienda invece di “Amministrazione Django” (e, per la cronaca, questo è in conformità con la licenza BSD di Django).
Integrazione senza soluzione di continuità tra il sito principale e l’amministrazione: potresti voler passare tra le funzionalità del back office mentre navighi sul sito e viceversa, avendo un barra di navigazione comune.
Rivestimento estetico: mentre l’amministratore sembra a posto, e ha persino implementato i principi di responsive web design dalla versione 2 (funziona bene su entrambi, mobile e desktop), c’è molto che un foglio di stile ben elaborato può fare per migliorarne l’aspetto.
Funzionalità di bypass: potresti anche voler creare menu a discesa personalizzati per l’amministratore, visualizzando le opzioni che utilizzi davvero e nascondendo dall’interfaccia utente ciò che non ti serve veramente, il che potrebbe migliorare l’esperienza utente.

A Practical Example

Per questo esempio, e per non ripetereci, riprenderemo l’applicazione web di pubblicazione semplice che abbiamo iniziato per l’articolo Prototipazione di un’App Web con Django e Vue.js.

In breve:

a Django app with two models:
Articolo con campi nome autore (collegato), contenuto e slug
Autore: con campi nome e slug
A single view called frontend that queries all registries in both models.
A single template called template.
Implementazione di Vue.js con Vue Router e Vuex per un’interfaccia reattiva scalabile.

Non ci preoccuperemo in particolare dell’integrazione di Vue.js in questo episodio e non lo modifichiamo qui.

Il Modello Base

Template Django sono molto versatili e potenti e possono essere creati a livello di app (un componente del sito Django) o a livello di sito, e possono anche sovrascrivere i template forniti con Django (che è quello che faremo qui).

Abbiamo creato un modello base che si collega a Bootstrap JavaScript e foglio di stile, e anche alle sue strumenti complementari, jQuery e Popper.

Ecco il modello di base che stiamo utilizzando per il sito principale, non molto diverso da quello che useremmo normalmente per qualsiasi altro sito Django:

<!doctype html>
<html lang="en">
  <head>
    <!-- Meta tag obbligatorie -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

    <!-- CSS di Bootstrap -->
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css" integrity="sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh" crossorigin="anonymous">

    <title>Django and Vue.js</title>
  </head>
  <body class="bg-light">
    <div class="bg-white container">
      <h1>Prototyping a Web App with Django and Vue.js</h1>

      <!-- Contenuto -->
    </div>

    <!-- Vue.js -->
    <script src="https://unpkg.com/vue"></script>
    <script src="https://unpkg.com/vue-router"></script>

    <!-- jQuery per primo, poi Popper.js, poi Bootstrap JS -->
    <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js" integrity="sha384-wfSDF2E50Y2D1uUdj0O3uMBJnjuUD4Ih7YwaYd1iqfktj0Uod8GCExl3Og8ifwB6" crossorigin="anonymous"></script>
  </body>
</html>

Successivamente, integreremo questo nell’admin e aggiungeremo una barra di navigazione condivisa su entrambi i lati — il sito principale e l’ufficio back office!

Integrazione del Modello UI Principale con l’Amministratore

Come accennato, possiamo sovvertire i modelli, compresi quelli dell’amministratore. Tuttavia, a causa della progettazione di Django e, non sorprendentemente, il sito principale e l’ufficio back office sono due sistemi diversi, ciascuno con i propri modelli, fogli di stile e pacchetti contrib. Quindi, anche se saranno quasi identici, dovremo mantenere due modelli diversi — uno per l’UI principale e uno per l’amministratore.

Abilitazione di una Directory per i Modelli in Generale

Per prima cosa, dobbiamo informare Django dove archiviaremo il modello di amministrazione modificato nella directory di base.

Quindi dovremo modificare myproject/settings.py. Prima di tutto, trova la costante TEMPLATES e questo tasto DIRS:

'DIRS': [],

Cambia quel codice in questo:

'DIRS': [os.path.join(BASE_DIR, 'templates')],

Avvolgimento del Template Admin (`admin/base` Hack)

Se volessimo apportare solo modifiche estetiche, come passare un foglio di stile personalizzato all’admin, o rimuovere/sostituire il suo header, potremmo farlo modificando il template admin/base_site e saltando completamente questo passaggio attuale. Tuttavia, se vogliamo andare fino in fondo e “avvolgere” (wrap) la sezione amministrativa come se fosse contenuta nel nostro sito principale, con la possibilità di avere un header e un footer comuni, continuate a leggere.

Dobbiamo copiare il admin/base.html di Django nella nostra directory dei template in templates/admin/base.html, in modo da poter inserire i nostri wrapper.

Modificheremo il codice intorno alla sezione container, in modo che passi da questo:

<!-- Container -->
<div id="container">
(...)
</div>
<!-- END Container -->

a questo:

{% block bodyheader %}{% endblock %}

<!-- Container -->
<div id="container">
(...)
</div>
<!-- END Container -->

{% block bodyfooter %}{% endblock %}

E questo è tutto! Abbiamo semplicemente creato i tag blocchi bodyheader e bodyfooter, in modo da poter inserire il codice che avvolgerà l’amministrazione nel passaggio successivo.

Codifica di un Template Admin Personalizzato (`admin/base_site` Hack)

Quindi, codifichiamo il template effettivo in templates/admin/base_site.html (dovremo creare le directory nella root del nostro progetto):

{% extends "admin/base_site.html" %}

{% block title %}Django with Bootstrap | Admin site{% endblock %}

{% block branding %}{% endblock %}
{% block breadcrumbs %}{% endblock %}

{% block bodyclass %}bg-light{% endblock %}

{% block extrastyle %}
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css" integrity="sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh" crossorigin="anonymous">
    <style>
      #header, .breadcrumbs { display: none; }

      /* Problemi di Bootstrap con l'admin */
      * { box-sizing: unset; }
      div.module caption { caption-side: top !important; }
      .collapse { display: block !important; }
    </style>
{% endblock %}

{% block bodyheader %}
    <div class="bg-white container">

      <div class="jumbotron">
        <h1 class="display-4">Hacking the Django Admin with Bootstrap</h1>
        <p class="lead">
          The <a ref="https://docs.djangoproject.com/en/dev/ref/contrib/admin/">Django administration site</a> is great—full-featured, easy to use, secure by design, rock solid… and somewhat ugly, which can be something of a downside when you want to integrate it with the look-and-feel of the rest of the website. Let’s sort that out.
        </p>
      </div>
{% endblock %}

{% block bodyfooter %}
    </div>

    <!-- jQuery prima, poi Popper.js, poi Bootstrap JS -->
    <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js" integrity="sha384-wfSDF2E50Y2D1uUdj0O3uMBJnjuUD4Ih7YwaYd1iqfktj0Uod8GCExl3Og8ifwB6" crossorigin="anonymous"></script>
{% endblock %}

Scomposizione

Cerchiamo di spiegare cosa stiamo facendo qui:

Diciamo all’engine del template che stiamo “estendendo” il template admin/base_site.html, per sovvertire efficacemente alcune delle sue definizioni.
Utilizziamo il blocco title per personalizzare un titolo per la pagina di amministrazione in navigazione.
Svuotiamo il contenuto dei blocchi branding e breadcrumbs, poiché non li abbiamo davvero bisogno.
Utilizziamo il blocco bodyclass per impostare bg-light di Bootstrap, come abbiamo fatto nel template frontend.
Utilizziamo il blocco extrastyle per incorporare Bootstrap e alcuni codici CSS.
a. Va bene, #header, .breadcrumbs { display: none; } è una sorta di riproposizione del numero 3; ma è utile sapere che puoi disabilitare le sezioni di branding e breadcrumbs in entrambi i modi.
b. Possono esserci alcuni problemi quando si sovrappone Bootstrap con CSS di Django nell’admin, quindi queste sono alcune correzioni.
Utilizza i blocchi bodyheader e bodyfooter per avvolgere il contenuto dell’admin.

Ora che abbiamo accesso al template dell’admin, potremmo ulteriormente il suo foglio di stile, o lasciarlo così com’è con uno stile condiviso con l’interfaccia principale.

Caveat

Stiamo mantenendo due diversi template (interfaccia principale e amministrativa) per presentare essenzialmente lo stesso contenuto. Ammettiamo che questo non sia l’ideale, poiché stiamo esplicitamente violando uno dei massimi dello sviluppo software: non ripeterti (DRY).

Come abbiamo commentato, questo accade perché l’amministratore Django è stato progettato per essere distaccato dall’interfaccia principale. E non c’è nulla di sbagliato in questo, proprio come non c’è nulla di sbagliato nel pensare fuori dagli schemi. Ma sì, ciò ci obbliga a utilizzare due template con contenuto quasi identico.

In realtà, in linea di principio potremmo progettare un pattern di template che includa quella navbar e altri elementi comuni dall’interfaccia principale e dall’amministratore, e riutilizzarli da quella singola fonte; ma a questo punto, e per lo scopo di questo articolo, tale approccio sarebbe un po’ eccessivo. Comunque, lascerò l’idea in serbo per te. 😉

Creare una Navbar Comune

Ora che l’interfaccia principale e il sito amministrativo sembrano quasi identici, possiamo andare oltre nella nostra integrazione e creare un’esperienza di navigazione comune… e ancora oltre, presentare alcune opzioni amministrative direttamente nel menu principale!

Ecco lo snippet per la navbar:

<nav class="navbar navbar-expand-lg navbar-light bg-light">
  <ul class="navbar-nav mr-auto">
    <li class="nav-item">
      <a
        class="nav-link text-primary"
        href="/author/"
      >
        Go to Authors
      </a>
    </li>
    <li class="nav-item">
      <a
        class="nav-link text-primary"
        href="/article/"
      >
        Go to Articles
      </a>
    </li>
    {% if user.is_authenticated %}
    <li class="nav-item dropdown">
      <a
        aria-expanded="false"
        aria-haspopup="true"
        class="font-weight-bold nav-link text-primary dropdown-toggle"
        data-toggle="dropdown"
        href="#"
        role="button"
      >
        Admin
      </a>
      <div class="dropdown-menu">
        <a class="dropdown-item" href="/admin/myapp/author/">
          Manage authors
        </a>
        <a class="dropdown-item" href="/admin/myapp/article/">
          Manage articles
        </a>
      </div>
    </li>
    {% endif %}
  </ul>
</nav>

Nota la sezione dropdown-menu, che si occuperà di presentare un menu amministrativo (vedi il componente Navbar di Bootstrap per maggiori dettagli).

Effettuiamo anche un controllo condizionale con {% if user.is_authenticated %} /{% endif %}, per decidere se mostrare o meno il menu amministrazione.

Infine, ricorda che, poiché ora stiamo mantenendo due diversi template principali, dovremo aggiungere il codice HTML della navbar a entrambi, myapp/templates/myapp/template.html e templates/admin/base_site.html.

Extra: Schermata di Login dell’Admin

Il sito amministrativo è stato curato, ma rimane un punto lasco: la schermata di login.

Ora potremmo trasformare qualcosa di simile a questo:

… in qualcosa di simile a questo:

Possiamo ottenere qualcosa di più vicino a ciò creando il seguente template in templates/admin/login.html:

{% extends "admin/login.html" %}

{% load i18n static %}

{% block extrastyle %}
{{ block.super }}
<style>
#header {
  background-color: transparent !important;
}
</style>
{% endblock %}

{% block branding %}
<h1>
  <span style="color: #57C5A5 !important">ActionPlanNow.com</span>
  <br />
  <small>{% block head_title %}{% endblock %}</small>
</h1>
{% endblock %}

{% block content_title %}
<p class="lead" style="font-size: larger">
A Simple Tool for Leaders, Coaches, and Counselors.
</p>
{% endblock %}

Spiegazione

Cosa stiamo facendo qui:

Il tag {{ block.super }} è lì per dire al motore del template che non stiamo sovrascrivendo il contenuto di extrastyle (definito nel template templates/admin/base_site.html) ma che stiamo semplicemente aggiungendo contenuto ad esso (vedi ereditarietà dei template per maggiori dettagli).
Il blocco branding ci permette di cambiare il titolo “Amministrazione Django” in qualcosa di più interessante.
Eliminiamo il blocco head_title impostando una definizione vuota.
Utilizziamo il blocco content_title per aggiungere alcune informazioni extra.

Alcune Considerazioni

Proprio come Bootstrap, anche il sito di amministrazione Django è fornito con il suo pacchetto di jQuery, ma per fortuna i sviluppatori di Django hanno pensato a questo e per evitare conflitti con script e librerie fornite dall’utente, jQuery di Django è namespace come django.jQuery. Quindi possiamo includere in sicurezza la propria copia (come abbiamo fatto).

Fai attenzione quando si va pazzo con le definizioni di classe nel foglio di stile principale, poiché questo influenzerà anche il sito di amministrazione, influenzandone la funzionalità in modi imprevisti. In tal caso, puoi sempre vedere cosa sta succedendo con gli strumenti di debug del browser, come Chrome DevTools, Firefox Developer Tools (in particolare Page Inspector), o Safari Developer Tools.

Demo e Codice Completo

Questa implementazione di cui abbiamo discusso apparirà così:

Puoi navigare tutto il codice del progetto nel mio repository GitHub, luzdealba / djangovuejs.

Riassunto

Mentre alcuni potrebbero sostenere — ragionevolmente — che non c’è molta necessità di modificare l’aspetto dell’amministrazione di Django, è anche vero che l’integrazione fluida dei diversi endpoint di un sito è un ottimo stratagemma per migliorare l’UX, poiché può fornire una transizione senza soluzione di continuità tra i due e anche una navigazione più controllata dell’amministrazione.

E farlo non è poi così difficile. Ciò a cui devi prestare attenzione è come avvolgi l’amministrazione e anche come mescoli librerie di terze parti con il tuo codice JavaScript e fogli di stile personalizzati. Fortunatamente, puoi integrare facilmente alcuni elementi nell’amministrazione, altri nel resto del sito principale e altri in entrambi.

Spero che tu abbia avuto delle idee su come puoi personalizzare ulteriormente Django in modi che non erano così evidenti!

Se hai bisogno di una scusa per costruire un’app web solo per giocare con l’amministrazione di Django, dai un’occhiata al tutorial della settimana scorsa su prototipizzare un’app web con Django e Vue.js — è un sacco di divertimento. E se vuoi approfondire le tue competenze con Django, la SitePoint Premium dispone di una vasta gamma di risorse per te.

Domande Frequenti (FAQ) sulla Personalizzazione dell’Amministrazione di Django con Bootstrap

Quali sono i vantaggi della personalizzazione dell’Amministrazione di Django con Bootstrap?

Personalizzare Django Admin con Bootstrap offre diversi vantaggi. Innanzitutto, migliora l’aspetto visivo dell’interfaccia amministrativa, rendendola più user-friendly e intuitiva. Bootstrap è un popolare framework front-end che fornisce una varietà di modelli di design per la tipografia, i form, i pulsanti e altri componenti dell’interfaccia. Integrandolo con Django Admin, puoi sfruttare questi modelli per creare un’interfaccia amministrativa più accattivante e funzionale. In secondo luogo, ti permette di aggiungere funzionalità personalizzate alla tua interfaccia amministrativa. Ad esempio, puoi aggiungere azioni personalizzate, filtri e form per migliorare l’usabilità dell’interfaccia amministrativa. Infine, può migliorare la risposta dell’interfaccia amministrativa, rendendola più accessibile su diversi dispositivi e dimensioni dello schermo.

Come posso aggiungere azioni personalizzate a Django Admin?

Django Admin ti consente di aggiungere azioni personalizzate che possono essere eseguite su oggetti selezionati. Per aggiungere un’azione personalizzata, devi definire una funzione che esegue l’azione desiderata sugli oggetti selezionati. Questa funzione dovrebbe avere tre parametri: l’amministratore del modello, la richiesta e un queryset degli oggetti selezionati. Una volta definita questa funzione, puoi aggiungerla all’attributo ‘azioni’ del tuo amministratore del modello. Ciò renderà l’azione disponibile nel menu a tendina delle azioni sulla pagina di modifica della lista amministrativa.

Posso personalizzare l’aspetto e il feeling di Django Admin utilizzando Bootstrap?

Sì, puoi personalizzare l’aspetto e il feeling dell’Admin Django utilizzando Bootstrap. Bootstrap è un framework front-end che offre una varietà di modelli di progettazione per la tipografia, i moduli, i pulsanti e altri componenti dell’interfaccia. Integrandolo con l’Admin Django, puoi sfruttare questi modelli per creare un’interfaccia amministrativa più accattivante e funzionale. Puoi personalizzare i colori, i font, il layout e altri elementi di design della tua interfaccia amministrativa per adattarli alla tua identità aziendale o a preferenze personali.

Come posso aggiungere filtri personalizzati all’Admin Django?

L’Admin Django ti consente di aggiungere filtri personalizzati che possono essere utilizzati per filtrare gli oggetti visualizzati sulla pagina della lista di modifica dell’amministratore. Per aggiungere un filtro personalizzato, devi definire una sottoclasse di django.contrib.admin.SimpleListFilter. Questa sottoclasse dovrebbe definire due metodi: lookups e queryset. Il metodo lookups dovrebbe restituire una lista di tuple, ciascuna rappresentante un’opzione di filtro. Il metodo queryset dovrebbe restituire un set di query filtrato in base all’opzione di filtro selezionata. Una volta definita questa sottoclasse, puoi aggiungerla all’attributo ‘list_filter’ del tuo amministratore del modello.

Posso usare Bootstrap con l’Admin Django senza alcun pacchetto aggiuntivo?

Mentre è possibile utilizzare Bootstrap con l’Admin Django senza alcun pacchetto aggiuntivo, è generalmente più semplice ed efficiente utilizzare un pacchetto come django-admin-bootstrap. Questo pacchetto fornisce un tema basato su Bootstrap per l’Admin Django, rendendo più semplice l’integrazione di Bootstrap con l’Admin Django. Offre anche funzionalità aggiuntive come il design responsivo e la rendering dei moduli personalizzati, che possono ulteriormente migliorare l’usabilità e la funzionalità della tua interfaccia amministrativa.

Come posso personalizzare i campi del modulo in Django Admin?

Django Admin ti permette di personalizzare i campi del modulo utilizzati per creare o modificare oggetti. Per personalizzare un campo del modulo, devi sovrascrivere il metodo ‘formfield_for_dbfield’ del tuo admin del modello. Questo metodo dovrebbe restituire un’istanza di campo modulo che verrà utilizzata per il campo dati specificato. Puoi personalizzare gli attributi del campo modulo, i widget e il comportamento di convalida secondo le tue esigenze.

Posso aggiungere viste personalizzate a Django Admin?

Sì, puoi aggiungere viste personalizzate a Django Admin. Per aggiungere una vista personalizzata, devi definire un metodo nel tuo admin del modello che gestisce la logica della vista. Questo metodo dovrebbe accettare una richiesta come unico parametro e restituire una risposta. Puoi quindi mappare questo metodo a un URL aggiungendo un modello di URL al metodo ‘get_urls’ del tuo admin del modello. Ciò renderà la vista accessibile dall’interfaccia amministrativa.

Come posso personalizzare la visualizzazione della lista in Django Admin?

Django Admin ti consente di personalizzare la visualizzazione della lista, che è la tabella di oggetti visualizzata sulla pagina di modifica della lista amministrativa. Per personalizzare la visualizzazione della lista, puoi impostare l’attributo ‘list_display’ del tuo admin del modello su un elenco di nomi di campi che desideri visualizzare. Puoi anche includere nomi di metodi in questo elenco, che richiameranno il metodo corrispondente su ciascun oggetto e visualizzeranno il risultato.

Posso usare Django Admin per modelli di database complessi?

Sì, Django Admin è progettato per gestire modelli di database complessi. Offre una varietà di funzionalità che possono aiutarti a gestire strutture dati complesse, come la modifica inline di oggetti correlati, campi modulo personalizzati e azioni personalizzate. Tuttavia, per strutture dati molto complesse o operazioni avanzate su database, potresti dover estendere Django Admin con viste, moduli o azioni personalizzate.

Come posso migliorare le prestazioni di Django Admin?

Ci sono diversi modi per migliorare le prestazioni di Django Admin. Un modo è ottimizzare le query del tuo database. Django Admin genera automaticamente query database in base alle definizioni del modello e alle opzioni di amministrazione. Tuttavia, tali query possono talvolta risultare inefficienti, specialmente per strutture dati complesse o grandi dataset. Personalizzando le tue opzioni di amministrazione e utilizzando le funzionalità di ottimizzazione del database di Django, puoi ridurre significativamente il numero di query database e migliorare le prestazioni dell’interfaccia di amministrazione. Un altro modo è utilizzare la memorizzazione nella cache. Django fornisce un robusto framework di caching che puoi utilizzare per memorizzare nella cache i risultati di operazioni costose o dati acceduti frequentemente. Utilizzando la memorizzazione nella cache, puoi ridurre il carico sul tuo database e migliorare la reattività dell’interfaccia di amministrazione.