djangoproject/first_django_app.md

# First Django App

Target: create a basic poll application, with 2 parts a **public site** and a **admin site**

* **public site**: let's pp view polls and vote
* **admin site**: let's you(admin) add/change/delete poll

## Creating a project

In the source directory, create project by

```
$ django-admin startproject <project_name>
```

Constraint on `<project_name>`:
* don't use names that conflict with django
  * e.g. `django`, `test` (test with built-in test file)

```
mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
```

Explain file structure:
* top-level `mysite/`: container of the project, can be renamed latter w/o affect Django framework
* `manage.py`: cmd-line utility let us to interact (admin) with Django projects.
* inner `mysite/` dir: actual Python package for the project. 
  * Importing any package from here: e.g. `mysite.urls`
* `mysite/__init__.py`: empty file, tell python start from here.
* `mysite/settings.py`: settings/config for this django project. 
* `mysite/urls.py`: URL declarations for this Django pjt; a "table of contents" of this Django website.
* `mysite/asgi.py`: An entry-point for ASGI-compatible webservers
* `mysite/wsgi.py`: Entry-point for WSGI-compatible webservers

## The development server

Start server steps:
1. cd into outer `mysite/` dir
2. Start server via: `python manage.py runserver`

Outcome:

* A development server is started. So no need to config a production server (e.g. Apache)
* Note: don't use it as production environment.

## Creating the Polls app

> Projects vs. apps
> 
> What’s the difference between a project and an app? An app is a Web application that does something – e.g., a Weblog system, a database of public records or a small poll app. A project is a collection of configuration and apps for a particular website. A project can contain multiple apps. An app can be in multiple projects.

Create a poll app along `mysite/`. For what?

```
$ python manage.py startapp polls
```

app hierarchy

```
polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py
```

## Write the first view

### Step 1: Create a simple view of `polls` app

modify `polls/views.py` as

```python
from django.http import request
from django.shortcuts import render

def index(request):
    return HttpResponse("Hello, world. You're at the polls index")
```

* `def index(request):...` is the simplest view

### Step 2: In `polls` app, map the URL to this view

After creating a view, map it to a URL so we can call it. Create `polls/urls.py`, and setup mapping `urlpatterns`

```python
from django.urls import path

from . import views

urlpatterns = [
    path('', views.index, name='index'),
]
```

### Step 3: Point the root URLconf for polls

To point the root URLconf at `polls.urls` module:
1. In `mysite/urls.py`
   1. add import for `django.urls.inclue`
   2. insert a `include()` in `urlpatterns` list

i.e.

```python
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('polls/', include('polls.urls')),
    path('admin/', admin.site.urls),
]
```

#### django.urls.include()

> django.urls.include(): A function that takes a full Python import path to another URLconf module that should be “included” in this place.

* new imported `include()` function allows referencing other URLconfs.
* `'polls.urls'` is the package that we are using, hence `mysite` can connect to `polls` app

#### path()

Here `path()` function is passed **route** and **view**; two additional option available **kwargs**, and **name**

* `path()` argument **route**: a string that contains a URL pattern. When Django processing a request, it starts at the first pattern in `urlpatterns` and go down the list, comparing requested URL against each pattern
* `path()` argument **view**: when Django finds a matching pattern, it calls specified view function (a `HttpRequest` obj as the 1st argument, and others captured values as keyword argument)
* `path()` argument **kwargs**: passed in a dictionary to the target view
* `path()` argument **name**: naming URL, so we can refer to it elsewhere.