# Documentazione Django 6.0.7

# Come gestire file statici (Es. immagini, JavaScript, CSS)

Websites generally need to serve additional files such as images, JavaScript, or CSS. In Django, we refer to these files as «static files». Django provides `django.contrib.staticfiles` to help you manage them.

Questa pagina descrive come puoi distribuire questi file statici.

## Configurazione file statici

1. Assicurati che `django.contrib.staticfiles` sia inserito in `INSTALLED_APPS`.

2. Nel tuo file dei settings, definisci `STATIC_URL`, per esempio:

       STATIC_URL = "static/"

3. In your templates, use the `static` template tag to build the URL for the given relative path using the configured `staticfiles` `STORAGES` alias.

       {% load static %}
       <img src="{% static 'my_app/example.jpg' %}" alt="My image">

4. Archivia i tuoi file statici in una cartella chiamata `static` nella tua app. Per esempio `my_app/static/my_app/example.jpg`.

Servire i file

In aggiunta a questi passaggi di configurazione, hai anche bisogno effettivamente di distribuire file statici.

Durante lo sviluppo, se usi `django.contrib.staticfiles`, sarà fatto automaticamente da `runserver` quando `DEBUG` è `True` (vedi `django.contrib.staticfiles.views.serve()`).

Questo metodo è altamente inefficiente e probabilmente poco sicuro, per questo è inadeguato alla produzione.

Consulta la documentazione Come distribuire file statici per le migliori strategie per distribuire file statici in ambienti di produzione.

Il tuo progetto avrà probabilmente anche asset statici che non sono legati ad una app particolare. Oltre ad usare una directory `static/` nelle tue applicazioni, puoi definire una lista di directory (`STATICFILES_DIRS`) nel tuo file di impostazioni dove Django cercherà ulteriormente i file statici. Per esempio:

    STATICFILES_DIRS = [
        BASE_DIR / "static",
        "/var/www/static/",
    ]

Consulta la documentazione per la configurazione relativa a `STATICFILES_FINDERS` per i dettagli su come `staticfiles` trova i tuoi files.

Namespacing dei file statici

Come per i template, potremmo semplicemente inserire i nostri file statici direttamente in `my_app/static/` (anziché creare un’altra sottodirectory `my_app`), ma sarebbe certamente una cattiva idea. Django sceglierà il primo file statico che troverà con un nome che corrisponde, e se tu avessi un file statico con lo stesso nome in una app diversa, Django non saprebbe come distinguere fra i due. Dobbiamo essere in grado di puntare Django sul file corretto, ed il modo migliore per farlo è quello di inserirlo in un namespace. Cioè, inserendo questi file statici dentro un’altra directory che abbia come nome il nome della app stessa.

Puoi assegnare namespace agli asset statici in `STATICFILES_DIRS` specificando prefissi.

## Servire file statici durante lo sviluppo

Se usi `django.contrib.staticfiles` come spiegato sopra, `runserver` lo farà automaticamente se `DEBUG` è impostato su `True`. Se non hai `django.contrib.staticfiles` in `INSTALLED_APPS`, puoi comunque servire manualmente i file statici usando la vista `django.views.static.serve()`.

Questo non è adatto per un utilizzo in produzione! Per alcune strategie di pubblicazione comuni, guarda Come distribuire file statici.

Per esempio, se la tua impostazione `STATIC_URL` è definita come `static/`, puoi fare questo aggiungendo il seguente snippet a `urls.py`:

    from django.conf import settings
    from django.conf.urls.static import static

    urlpatterns = [
        # ... the rest of your URLconf goes here ...
    ] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

Nota

Questa funzione helper funziona solo in modalità debug e solo se il prefisso dato è locale (ad esempio `static/`) e non un URL (es: `http://static.example.com/`).

Anche questa funzione helper serve solo la cartella `STATIC_ROOT`; non esegue la disocvery dei file statici come `django.contrib.staticfiles`.

Infine, i file statici sono serviti via wrapper al livello di applicazione WSGI. Di conseguenza, le richieste a file static non passano attraverso la normale catena di middleware.

## Distribuire file caricati da un utente durante lo sviluppo

Durante lo sviluppo, è possibile servire file multimediali caricati dall’utente da:setting:MEDIA_ROOT utilizzando la vista `django.views.static.serve()`.

Questo non è adatto per un utilizzo in produzione! Per alcune strategie di pubblicazione comuni, guarda Come distribuire file statici.

Ad esempio, se il tuo `MEDIA_URL` è definita come `media/`, puoi farlo aggiungendo il seguente snippet al tuo:setting:ROOT_URLCONF:

    from django.conf import settings
    from django.conf.urls.static import static

    urlpatterns = [
        # ... the rest of your URLconf goes here ...
    ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Nota

Questa funzione di supporto è disponibile solo in modalità debug e solo se il prefisso è locale (es. `media/`) ma non unaURL (es. `http://media.example.com/`).

## Testing

Quando si eseguono test che utilizzano richieste HTTP effettive invece del client di test integrato (per esempio utilizzando `LiveServerTestCase`) gli asset statici devono essere serviti insieme al resto del contenuto in modo che l’ambiente di test riproduca quello reale il più fedelmente possibile, ma `LiveServerTestCase` ha solo funzionalità di servizio di file statici molto basilari: non conosce la funzione di ricerca dell’applicazione `staticfiles` e presuppone il il contenuto statico sia già stato collezionato in `STATIC_ROOT`.

A causa di ciò, `staticfiles` offre la propria `django.contrib.staticfiles.testing.StaticLiveServerTestCase`, una sottoclasse di quella built-in che ha l’abilità di servire trasparentemente tutti gli asset durante l’esecuzione di questi test in modo molto simile a quello che si ottiene durante lo sviluppo con `DEBUG = True`, cioè senza doverli collezionare usando prima `collectstatic`.

## Deployment

`django.contrib.staticfiles` fornisce un comando di gestione comodo per la raccolta di file statici in un’unica directory in modo da poterli servire facilmente.

1. Imposta il valore di `STATIC_ROOT` alla directory da cui desideri servire questi file, ad esempio:

       STATIC_ROOT = "/var/www/example.com/static/"

2. Run the `collectstatic` management command:

       $ python manage.py collectstatic

   Questo copia tutti i file dalla tua cartella static nella cartella definita in `STATIC_ROOT` .

3. Utilizza un web server a tua scelta per distribuire i files. Come distribuire file statici copre alcune delle strategie di distribuzione comuni per i file statici.

## Per saperne di più

Questo documento ha coperto le basi ed alcuni pattern di utilizzo comuni. Per avere dettagli completi su tutte le impostazioni, i comandi, i tag di template ed altri frammenti inclusi in `django.contrib.staticfiles`, visita la guida di riferimento di staticfiles.