django static files briefer

django_staticfiles.markdown

##The django static files (how I understand them):

I will refer to the staticfiles app as 'staticfiles' in this document... ie, staticfiles gets installed as an app in django when django.contrib.staticfiles is in settings.py's INSTALLED_APPS variable.

I think the confusion with staticfiles is based on the fact that the documentation mashes a bunch of different things together, specifically whether or not staticfiles is used to serve files in 1. development mode and/or 2. production mode. Additionally, its 3. capabilities outside of serving static files, the staticfiles app could also through the use of the python manage.py collectstatic command collect your static files from all sorts of different locations (local file system, cloud, etc) and download them to what's specified in STATIC_ROOT. You could setup your production http server to serve the files out of STATIC_ROOT for STATIC_URL after they've been collected there.

1. Development Mode.

If your project is in development mode (debug=True) and you're running the development server (runserver command), staticfiles will serve the staticfiles located in your settings.py STATICFILE_DIRS absolute path(s) at STATIC_URL's url. This means that the path in STATIC_ROOT during development mode will not be served unless it is also specified in STATICFILES_DIRS. Append any additional static file paths to the STATICFILES_DIRS settings.py variable. There's also the STATICFILES_FINDERS settings.py variable which behaves very similar to the TEMPLATE_LOADERS variable in that there's a module that will search your app's path for static files, 'django.contrib.staticfiles.finders.AppDirectoriesFinder'. Unfortunately this isn't the final step in the process, urls.py needs to be configured to forward the static file requests to the staticfiles app. There are 3 ways from the documentation to configure urls.py.

#####a. From the docs:

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf goes here ...

urlpatterns += staticfiles_urlpatterns()

#####b. You could also add additional paths for staticfiles to search here. From the docs:

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

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

#####c. You could add additional paths for staticfiles to search here as well. From the docs:

from django.conf import settings

# ... the rest of your URLconf goes here ...

if settings.DEBUG:
    urlpatterns += patterns('',
        url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
            'document_root': settings.MEDIA_ROOT,
        }),
   )

###2. Production Mode.

When in production mode (debug=False) and using the runserver command to serve your django project, staticfiles does NOT serve any of your static files from any location at STATIC_URL no matter what configuration options you have set or which method you chose to setup urls.py for staticfiles above -- 100% intentional by the django developers (see 'Warning' https://docs.djangoproject.com/en/dev/howto/static-files/?from=olddocs#serving-static-files-in-development).

###3. Capabilities Outside of Serving Static Files.

https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/#django-admin-collectstatic

###4. Gotchas.

1. Make your MEDIA_ROOT and MEDIA_URL different from your STATIC_ROOT and STATIC_URL. Check the 'Note': https://docs.djangoproject.com/en/dev/howto/static-files/?from=olddocs#deploying-static-files-in-a-nutshell

2. Don't forget to include the context processor so that the STATIC_URL variable is available in your templates.

from the docs:

The included context processor is the easy way. Simply make sure 'django.core.context_processors.static' is in your TEMPLATE_CONTEXT_PROCESSORS.

Once that's done, you can refer to STATIC_URL in your templates:

<img src="{{ STATIC_URL }}images/hi.jpg" alt="Hi!" />