|
* [[/Starting_our_project|Part 1: Starting our project]]
=== Part 1: Starting our project ===
This tutorial goes through the process of building a simple social bookmarking application, where users can save various URLs and tag those bookmarks to make them easier to find later. Our bookmarks application will be built on top of Django, a full-featured web framework written in Python.
==== Activate your env ====
The first step is to open your terminal window, navigate to your django-for-designers folder, and activate your env:
<!-- Teacher git note: There should be a pre-part-1 branch on Github that is to your liking. It should equal master on github. -->
<source lang="bash">
# in django-for-designers
$ source ./bin/activate</source>
You'll know it worked because afterwards, you'll see <source lang="bash">(django-for-designers) $</source> at the front of all your terminal lines in that terminal window!
(What this did is activate a special Python environment that knows about Django and other dependencies for this tutorial. By keeping our dependencies inside a separate environment, we can keep them from interfering with any other project's dependencies--for instance, if you had one project using Django 1.4 and another using Django 1.5 on the same computer.)
====Create a branch in your git repository====
If you're not familiar with git, git is a version control system that tracks changes you make to files within a git repository (the folder you just cloned). You make commits in git, which are like save points in video games -- the commit messages tell you what changes are included in this commit. If later on you make some changes and delete something or mess something up, you can always go back to a previous commit and try again.
Git also has "branches"--parallel timelines where you can go off from the main branch (called "master") and try something out. It's often a good idea to start a new branch when you're writing a new feature. You can make as many commits as you want inside the branch, and it won't affect the main master timeline. You can make as many branches as you want, and branches of branches. You can even share branches with others (though we won't be doing that today). Git's branching system (and its non-centralized architecture generally) make it easy to try out new ideas in code without having to ask permission of everyone else who might be working on the same code as you. Then, when your new feature is done, you can then merge (or rebase--the exact process would take a much longer explanation) the changes back into the master timeline.
We'll be using the master branch (the default name for the main branch of code, which you're in right now) of the git repository you cloned during laptop setup for syncing up throughout the class in case you get lost. You'll need to make your own branches for playing with the code on your computer, so that it doesn't interfere w. re-syncing later.
We've created some branches for you to base your work on. You will use snapshots these as starting points throughout the tutorial. At the end of a section, you'll have your own completed work for that section available, but you'll start fresh from a pristine snapshot of what it would have looked like if you did it our way.
To make sure you have the latest collection of those, run this command:
<source lang="bash">
# in django-for-designers
$ git fetch
</source>
To make your first branch, enter:
<source lang="bash">
# in django-for-designers
$ git branch my-branch-1 origin/pre-part-1
$ git checkout my-branch-1
</source>
Congratulations! You're now in a branch named my-branch-1! Notice that branches on your own computer have no prefix; branches that belong to use have ''origin/'' before their names.
You can see what branch you are in (and what branches are in your repository) at any time by typing:
<source lang="bash">
# in django-for-designers
$ git branch</source>
====Start your project====
Let's create your first Django project, which we'll call "myproject".
<source lang="bash">$ django-admin.py startproject myproject</source>
You'll see we made a folder called "myproject", with some files in it. Let's check them out!
<source lang="bash">
# in django-for-designers
$ cd myproject/
# in django-for-designers/myproject
$ ls
manage.py
myproject
$ ls myproject/
__init__.py
settings.py
urls.py
wsgi.py
</source>
These files are:
* manage.py: A command-line utility that lets you interact with this Django project in various ways.
* myproject/: Django auto-creates an folder within your project with the same name as your project that has a number of useful files in it. (This is a recent change; before Django 1.4, Django just put everything in the project folder instead of siloing it.)
* myproject/__init__.py: An empty file that tells Python that this directory should be considered a Python module. Because of the __init__.py file, you can use import to import myproject.
* myproject/settings.py: Settings/configuration for this Django project.
* myproject/urls.py: The URL declarations for this Django project; a “table of contents” of your Django-powered site.
Django comes with some local server software included. The Django development server is not hardy enough for actual production use (please, please don't use it for sites other people are supposed to see!) but it makes it easy to see the changes you make to your web app as you build it. Let's make sure our project works by verifying that the dev server will start:
<source lang="bash">
# in django-for-designers/myproject
$ python manage.py runserver</source>
(Note: If you see a ''python: can't open file'' error, make sure you have used ''cd'' to change into the directory with manage.py.)
You should see some output in your terminal that looks like:
<source lang="bash">Validating models...
0 errors found.
Django version 1.2, using settings 'myproject.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.</source>
Visit [http://localhost:8000/ http://localhost:8000] in your web browser, and you’ll see a “Welcome to Django” page, in pleasant, light-blue pastel. It worked! :)
Observe the logging that happens in the terminal where your server is running:
<source lang="bash">[24/Mar/2011 11:50:18] "GET / HTTP/1.1" 200 2057</source>
which has the format:
<source lang="bash">DATE METHOD URL PROTOCOL RESPONSE_CODE CONTENTSIZE</source>
Navigate to http://127.0.0.1:8000/some/url/. What changes in the terminal log?
Exit the server by returning to the terminal window where the development server is running and pressing CONTROL-C on your keyboard.
One super useful tip is to open a new terminal (a new tab, or a new window, on your convenience) and keep the runserver always open there. By default, Django's runserver will automatically reload to reflect any changes that you make, so there's no need to stop and start it.
Do that now to save you time later. Remember that you will need to ''cd'' into the right place, and ''activate'' the virtualenv again.
====Version control====
Before we do anything else, let’s commit our work in git.
As you recall, git lets you create checkpoints over the course of the time a program is being developed. Commits are those checkpoints. Programmers often have to go back into the history of a program to change things--whether it's to diagnose a bug or redesign how a feature works. Programmers also have to have an easy way of being able to edit the same application at the same time, and to share their edits with each other. Thus, besides '''saving''' their work the normal way, programmers '''commit''' their code using version control software.
Each commit contains the '''diff'''--the "difference", all of the changes you made to your code base -- between that commit and the commit before it. Different branches in git share the commits made prior to the branching-off point, then each have their own commit history.
To make a commit, first type <source lang="bash">
# in django-for-designers/myproject
$ git status</source> into your terminal. This will let you know what changes git has noticed in your code and which of those changes, if any, are staged and ready to be committed.
<source lang="bash">
# in django-for-designers/myproject
$ git status
# On branch my-branch-1
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# ./
nothing added to commit but untracked files present (use "git add" to track)</source>
"Untracked files" means that git has noticed some new files inside its repository folder, but you haven't told git explicitly that you want it to "listen" for, and track, changes in those files. './' means that the folder we're in right now is currently untracked.
* Add the folder:
<source lang="bash">
# in django-for-designers/myproject
git add ./
</source>
What does git status say now?
* git commit to commit those files. Adding the -m flag lets you say what the 'message' for the commit is in the same line:
<source lang="bash">
# in django-for-designers/myproject
$ git commit -m "Initial commit of Django project for the PyCon 2013 Django tutorial"
</source>
* Look at your changes with <source lang="bash">git log</source> to see your history. Is your commit message there?
Huzzah! We committed our changes so far. Now let's make some more changes!
====Set up your settings and database====
Now that we have a the scaffolding for our project in place, we can get to work! First, it needs to be configured.
Open myproject/myproject/settings.py in your editor. settings.py is a Python script that only contains variable definitions. Django looks at the values of these variables when it runs your project.
In settings.py, let's find DATABASES. The DATABASES variable is a dictionary (note the ‘{}’ characters) with one key: default.
<source lang="python">
DATABASES = {
'default': {
'ENGINE': 'django.db.backends', # Add 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
'NAME': '', # Or path to database file if using sqlite3.
'USER': '', # Not used with sqlite3.
'PASSWORD': '', # Not used with sqlite3.
'HOST': '', # Set to empty string for 127.0.0.1. Not used with sqlite3.
'PORT': '', # Set to empty string for default. Not used with sqlite3.
}
}</source>
Notice that the value of default is itself another dictionary with information about the site’s default database.
Set your app to use a sqlite database, in the ENGINE attribute. Sqlite is great for development because is stores its data in one normal file on your system and therefore is really simple to move around with your app. It's not sturdy enough to use for a website in production, though.
<source lang="python">'ENGINE': 'django.db.backends.sqlite3',</source>
Set your app to use a file called 'database.db' to store information for this project.
<source lang="python">'NAME': 'database.db',</source>
Does database.db exist right now? (No, but that's okay. It'll get created automatically when it's needed.)
Run git status, then git add and commit your change:
<source lang="bash">
# in django-for-designers/myproject
$ git add myproject/ # this is a shortcut that will add all changes inside the named folder
$ git commit -m "set up the database for Django to use"
</source>
Even though git knows to "listen" to settings.py now, it still won't add it to the 'staging area' for your commit unless you tell it to explicitly with git add.
Notice the INSTALLED_APPS setting towards the bottom of the settings.py. That variable (a python tuple... note the ‘()’ symbols) holds the names of all Django applications that are activated in this Django instance. Apps can be used in multiple projects, and you can package and distribute them for use by others in their projects. Some apps (as you can see) are installed by default!
Add South to our list of installed apps. (We'll need it later.)
<source lang="python">INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.messages',
'django.contrib.staticfiles',
# Uncomment the next line to enable the admin:
# 'django.contrib.admin',
# Uncomment the next line to enable admin documentation:
# 'django.contrib.admindocs',
'south',
)</source>
Each of our applications makes use of at least one database table, so we need to create the tables in the database before we can use them. To do that, run the following command in your terminal window:
<source lang="bash">
# in django-for-designers/myproject
$ python manage.py syncdb</source>
The syncdb command looks at the INSTALLED_APPS setting and creates any necessary database tables according to the database settings in your settings.py file. You’ll see a message for each database table it creates.
When prompted, you’ll get a prompt asking you if you’d like to create a superuser account for the authentication system. Say yes! Use 'super' as your password for now.
Does database.db exist right now? (Yes! Calling syncdb made Django realize it needed a sqlite database file, so it made one for us.)
Save and commit your work!
====Projects vs. apps distinction====
We’ve talked a little about Django apps and projects. You might be wondering what that nonsense is all about. Here are the things to know:
An app is component of a website that does something. South is a Django app. So is our bookmarks app (or it will be, anyway). An app is:
* single purpose - login, passwords, polls, forum, etc.
* orthogonal to / independent of other apps - Bookmarks shouldn’t have to know the inside details of authentication, for example.
A project corresponds roughly to a ‘website’: it has a settings.py file, and it may have corresponding databases or other data stores that the apps interact with. As you can remember, Django automatically made a folder for us called myproject, which you can think of as the app that coordinates all the other apps and other parts of the project.
Most projects--those for more complex websites--should use multiple apps, one for each core piece of functionality. Ideally, you should reuse existing free, open source Django apps that other people have written for things like user accounts, image galleries, and other common use cases. [http://www.djangopackages.com Django Packages] is a good resource for finding such apps.
You can find prewritten Django apps for things like bookmarks and tagging, but we'll be writing them ourselves for the sake of learning. :)
====Start your first app====
In your terminal, write:
<source lang="bash">
# in django-for-designers/myproject
$ python manage.py startapp bookmarks</source>
If you run
<source lang="bash">
# in django-for-designers/myproject
$ ls</source>
you'll see that now there is a folder called bookmarks/ in your project!
Inside that folder, you'll see:
<source lang="bash">
# in django-for-designers/myproject
$ ls bookmarks/
__init__.py
models.py
tests.py
views.py
</source>
Finally, we need to edit myproject/settings.py so that Django knows about our app. Open that file up, and look for INSTALLED_APPS. Add the following to the end of the sequence, on a line of its own:
<source lang="python">
'bookmarks',
</source>
It will then look like this:
<source lang="python">
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.messages',
'django.contrib.staticfiles',
# Uncomment the next line to enable the admin:
# 'django.contrib.admin',
# Uncomment the next line to enable admin documentation:
# 'django.contrib.admindocs',
'south',
'bookmarks',
)
</source>
Let's commit our new app.
<source lang="bash">
# in django-for-designers/myproject
$ git add bookmarks/
$ git commit -m "Made a bookmarks app"</source>
=== Part 2: URLs, basic views, templates, static files ===
|