djangular

A reusable app that provides better app integration with AngularJS. Djangular allows you to create AngularJS content per app, instead of creating a single massive AngularJS application inside of Django. This allows you to selectively use apps per site, as well as create a consistent structure across all of your Django apps.

This is intended to be a Django version of the angular-seed project (https://github.com/angular/angular-seed). The current mindset is to limit the amount of changes introduced by Djangular.

Features

• Allows namespacing AngularJS content per Django app. This allows the AngularJS apps and modules to be included (or not) based on Django's settings, and enforces a consistent structure to your Django/AngularJS apps.
• Includes an AngularJS module that includes a subset of features similar to what Django provides in its templates.
• Adds a patch to AngularJS's $resource module, to enable end of URL slashes that Django requires.
• Improves security by enabling of CSRF protection and JSON Vulnerability between Django and AngularJS.
• ~~Scripts to allow running JS Unit and E2E tests, similar to the Django test command.~~ This was removed for the time being and will be (re-)included in a future release.
• Does not dictate how you use AngularJS inside your Django app.

Requirements

• Currently requires Python 2.7.
• Supports Django >= 1.5, <= 1.9
• Supports AngularJS 1.2+ (including 1.3.x).
• ~~Local installs of Node.js and Karma for testing.~~

Installation

• You may install directly from pypi:

    pip install djangular
  

• Or download the source and install it in a terminal/console:

    python setup.py install
  

• Or download the source and move the djangular directory inside your django project as an app (this is the least recommended approach).

• Djangular needs to be placed as an app inside a Django project and added to the INSTALLED_APPS setting.

    INSTALLED_APPS = (
        ...
        'djangular',
        ...
    )
  

• You will need to obtain a version of AngularJS and place it in the static folder of one of your Django apps. Djangular no longer includes a version of AngularJS, since it updates too frequently.

Including AngularJS content in your Django Apps

The most popular feature of Djangular, this will both include and namespace your AngularJS content inside your Django apps. Each Django app has its own "angular" folder, with a layout matching the angular-seed project. As a result, the URLs for these get grouped into the STATIC_URL structure of Django.

• The staticfiles contrib library will need to be included in the INSTALLED_APPS setting.

    INSTALLED_APPS = (
        ...
        'django.contrib.staticfiles',
        'djangular',
        ...
    )
  

• The STATICFILES_FINDERS needs to be updated to include djangular.finders.NamespacedAngularAppDirectoriesFinder.

    STATICFILES_FINDERS = (
        'django.contrib.staticfiles.finders.FileSystemFinder',
        'django.contrib.staticfiles.finders.AppDirectoriesFinder',
        'djangular.finders.NamespacedAngularAppDirectoriesFinder'
    )
  

• Because of this new finder, the findstatic and collectstatic commands will place the angular files in each app in an associated an <app_name>/ folder. You will not need to namespace each of your static directories with the name of your Django application (unless you really want to).

  • Example: If you have a Django app named foo and you are using the default STATIC_URL in your settings, the main AngularJS module named foo would be found at foo/angular/app.js on the file system and at static/foo/app.js from the browser.
  • This namespacing is done automatically. This a foo app and a bar app can both have an app.js inside their angular directories, and they will not collide.
  • Note: Because of these URLs, referring to AngularJS content in a separate app should use a ../<separate_app>/ URL. This will help significantly during testing to make sure paths are correct.
  • Note: It is recommended to namespace the AngularJS code the same name as the Django app. The created JS files do this already.

• To create an app that is already setup with the djangular (or angular-seed) structure, run python manage.py startangularapp <app_name> from the command line. This will create the files and directory structures needed for you to get started.

Including some Django template-like features in your AngularJS templates

One of the challenges in using AngularJS inside of Django is that you may not have access to some needed variables that are always included in Django templates. Djangular includes an AngularJS module to help with that.

• To use the AngularJS module that Djangular provides you, you'll need to add the djangular app to your projects URLs.

    urlpatterns = patterns('',
        ...
        url(r'^djangular/', include('djangular.urls')),
        ...
    )
  

• Alternatively, you may specify the DjangularModuleTemplateView specifically, and customize the url.

    from djangular.views import DjangularModuleTemplateView
    ...
  
    urlpatterns = patterns('',
        ...
        url(r'<custom_path>/djangular.js',
            DjangularModuleTemplateView.as_view()),
        ...
    )
  

This will add a djangular AngularJS module to your front end code. This module includes a DjangoProperties constant that includes whether the current user is authenticated, the username, groups and roles of the current user and the static and media urls from Django settings. It also includes a django filter, which does some basic substitution based on the properties constant.

Enforcing the end slashes of your AngularJS Resources

$resource is a convenient way to create REST-like services in AngularJS. However, there currently is a bug in $resource that will strip the ending slash, which means that $resource is unusable unless settings.APPEND_SLASHES is set to FALSE.

Djangular used to patch this automatically, but it now includes a separate file (djangular/static/js/resource_patch.js) to handle this issue. Simply include that javascript file in your page after you have loaded angular-resource.js and ending slashes will be preserved in $resource.

Enabling CSRF protection in AngularJS Templates

Djangular includes a JSON Vulnerability middleware that AngularJS knows how to process. To include this protection, add djangular.middleware.AngularJsonVulnerabilityMiddleware to the MIDDLEWARE_CLASSES setting. This only affects JSON requests (based on Content-Type), so this can be located fairly low in the middleware stack.

    MIDDLEWARE_CLASSES = (
        ...
        'djangular.middleware.AngularJsonVulnerabilityMiddleware'
    )

Once you have enabled CSRF protection in Django by adding the middleware django.middleware.csrf.CsrfViewMiddleware to the MIDDLEWARE_CLASSES setting, you may use the same protection in AngularJS templates in addition to Django template. There are two different ways to enable this protection via djangular:

• Make your main app dependent on the djangular module and use the included csrf-token directive (that wraps the Django csrf_token template tag) inside the appropriate form tags in your HTML.

    // Inside your JavaScript
    angular.module('myApp', ['djangular', ...]);
    ...
    <!-- In your AngularJS Template -->
    <div ng-app="my-app">
        ...
        <form ...>
            <csrf-token></csrf-token>
        </form>
    </div>
  

• Make your main app dependent on the djangular.csrf, which will add the appropriate CSRF Token Header in all POSTs, PUTs and DELETEs. Note that this way is vulnerable to cross-site scripting if you make a post to a domain outside your control.

    angular.module('myApp', ['djangular.csrf', ...]);
  

If you allow a user to login (or logout) and don't redirect or reload the page, the tags and cookies provided by both methods above will be stale. The second option (using the djangular.csrf module) provides a UpdateCSRFToken function that can be invoked with the new CSRF Token value.

Using Djangular in your Django Project

This section describes some best practices in using Djangular. Please note that these are guidelines and recommendations, but not the only way to use this project.

AngularJS as purely static content

The first way to use djangular is to have all of your static content live inside an angular app. This is perhaps the "most correct" way from an AngularJS standpoint and perhaps the "least correct" way from a traditional Django perspective.

In doing this, you are only (or almost only) serving content from your static domain and your Django development becomes strictly back-end focused for REST and/or service calls. Few to none of your Django views will produce HTML. You can provide a redirect from a Django view to your static pages (if you like), although this can seem strange when your static content is served from a completely different domain. You may need to configure your web servers to allow remote Ajax calls from your static domain.

This approach allows you to use AngularJS with any number of back-ends, as (again) your Django app becomes an API for your AngularJS code to call. This approach can be very different from how your application is currently architected.

From our experience, if