Django is an incredibly-powerful web framework, but using it can be a bit daunting for new users. I found this out the hard way over a year ago, spending hours struggling with even the most basic of concepts. If you're new to Django, (or MVC frameworks in general), you're probably going to have to shift your thinking a bit to use this robust framework. Here are some of the issues that I had to struggle with before I fully understood them. Hopefully, this will save you hours of struggling.
1. It's Not a CMS
Django isn't a CMS. It can't do everything that WordPress or Drupal can do right out of the box. That said, you can do infinitely more with Django, because it isn't a CMS.
If you have a background with, for example, a platform like WordPress, it's going to take a while to wrap your head around the fact that you're going to have to do a lot more things manually, such as creating urls or modifying settings. Most of the configurations won't be done in a UI, but instead with Python files.
While Django does come with a pretty nifty admin area straight out of the box, configuring Django sometimes isn't as easy as a standard CMS.
2. Local Environment Setup
One of the biggest initial hurdles that new users face is configuring their local environment for Django. For many beginners, it takes longer to install the framework locally than to build their first app. PHP frameworks like CakePHP are pretty much ready to start using once you've downloaded them on your local machine.
Installing Django and configuring it to run on the local machine can be kind of tricky, especially if you're not familiar with concepts like symlinks. The Django install docs are pretty comprehensive, but if those don't work for you search for some video instruction or platform-specific documentation.
3. Projects vs. Apps
If you're new to Django (or MVC frameworks in general), odds are the terms "projects" and "apps" might be a little confusing.
With Django, a Project is just a collection of apps. Say you were building a YouTube clone; you would create a project, "MyTube", that would contain apps like "videos", "comments", "ratings", "blog", etc.
Apps are similar to modules in a CMS, except you build them from scratch. They're a lot smaller in scope, typically performing only one main function. For the MyTube example, you wouldn't just create one app that allowed users to upload videos, comment on them, rate them, and anything else. You want your apps to be small in scope, performing only one or two functions by themselves.
4. Template Inheritance
Template inheritance is one of the best features of Django, but it usually takes a while to truly understand.
With a traditional CMS, you might split reusable parts of a template out into their own files (like a header file), and include them in each of the templates. With Django, you create a base.html template, and you specify blocks that can be overwritten in child templates. This keeps your code more reusable.
So, for an example, you might have a base.html template that has this:
<div>
{% block content %}
<p>Here is our content that will be overwritten</p>
{% endblock %}
<p>Other stuff that won't be overwritten.</p>
</div>
Then in another template you may choose to overwrite the {% content %} block. Instead of having to include a sidebar file into the design, we just simply do something like this:
{% extends base.html %}
{% block content %}
I'd like a different content block!
{% endblock %}
This extends the base.html. This method allows you finer control over your templates, and ensures that you're not creating duplicate code.
To learn more about the power of template inheritance, check out this article on the power of Django template inheritance.
5. Separation of Code and Media Files
Because Django doesn't serve media files itself, it likes to separate the media files (images, JavaScripts, stylesheets, etc. ) into a directory away from the apps. This allows you to decide how you're going to serve those static files. You could use a separate webserver or cloud services like Amazon S3 to serve the files.
Your project files might look something like this:
MyProject
- app
- app2
- media
- javascript
- stylesheets
- images
....
6. Migrations
Database migrations are a trouble-spot for many beginners. This happens when you already have fields in your database (production or development), and you add something that modifies the database.
Other frameworks like Rails have database migrations built in. With Django, however, unless you use a third-party solution, you have to do the migrations by hand. Fortunately, there is an excellent third-party tool that handles Django migrations: South.
South allows you to perform database migrations, much like Rails allows, and is easy to roll into your existing project. It's powerful and simple, and takes care of the issue of database migrations that Django has. Here's a tutorial that has examples of how South works.
7. Local vs. Production Environments
Django comes with sqlite, a simple flat-file database that doesn't need any configuration. This makes prototyping fast and easy right out of the box.
However, once you've moved your project into a production environment, odds are you'll have to use a more robust database like Postgresql or MySQL. This means that you're going to have two separate environments: production and development.
Django doesn't really have logic baked in that allows you to easily switch between two different settings without manually editing the settings.py file. For example, having the setting
DEBUG = True
is helpful for local environments, because it provides helpful error messages when code goes bad. But if you're on a production environment, you'll never want users to see your error messages, so you'd need to specify –
DEBUG = False
.
There is a way to automatically toggle between the two environments, using this quick modification:
import socket
if socket.gethostname() == '<a href="http://productionserver.com" target="_blank">productionserver.com</a>':
DEBUG = False
else:
DEBUG = True
You can reuse the socket bit in different areas of your settings.py as well.
8. Writing Custom Template Tags
Template tags are an insanely useful aspect of Django. In fact, it ships with many built-in template tags right out of the box.
However, if you're wanting to write your own custom template tags, it can get a bit tricky. Here's a simple example of writing a custom template tag that should give you a better understanding of how template tags work and how to create your own.
9. Django User Authentication
Django comes with a great user authentication system in the project admin that you can use to manage users. However, the user authentication system doesn't provide a simple way to allow non-admins to create user accounts. CMSs, like Drupal, handle this beautifully right out of the box.
There are a few great options for public user authentication systems that provide this missing functionality. The most popular third-party solution is probably django-registration. It's simple yet flexible, and provides everything you need to get user signups in your application.
10. Generic Views
Generic views are incredibly powerful, and can save you a lot of time writing views for your Django app. However, most beginners don't know how useful and powerful they are.
For example, if you want to create a flat page for your homepage, but want to style it differently, you can create a template in your flatpages template directory that utilizes the direct_to_template view.
Aside from creating the proper template, you'll need to modify your urls.py file to point to it:
urlpatterns = patterns('',
(r'^$', 'django.views.generic.simple.<WBR>direct_to_template', {'template': 'homepage.html'}),
.....
Now, we have a homepage with a custom design that doesn’t require writing any custom views. I’ve utilized this technique many times instead of writing extra views.
Conclusion
Once you've worked through all the tricky areas that catch most beginners, Django will prove to be a really fast and powerful tool for building web applications. Don't get discouraged if you find yourself confused early on. You can always find help within the Django IRC channel; Stackoverflow is another excellent place to ask questions.