# Django 5.2.9 - dokumentacja

# Django w skrócie

Jako że Django było rozwijane w dynamicznym środowisku prasowego newsroomu, zostało zaprojektowane w taki sposób, aby robić częste web-deweloperskie zadania szybko i prosto. Poniżej przedstawiamy nieformalny opis jak napisać opartą na bazie danych aplikację webową z Django.

Celem tego dokumentu jest prezentacja takiej ilości technicznej specyfiki, abyś zrozumiał jak Django działa, ale nie jest on przeznaczony do bycia tutorialem lub dokumentacją – mamy ich oboje! Kiedy będziesz gotowy, aby zacząć projekt, możesz rozpocząć tutorial lub zanurzyć się w bardziej szczegółowej dokumentacji.

## Zaprojektuj swój model

Pomimo że możesz używać Django bez bazy danych, ma on wbudowany mapper obiektowo-relacyjny, za pomocą którego możesz opisać układ swojej bazy danych pythonowym kodem.

Składnia modeli danych oferuje wiele bogatych sposobów przedstawiania modeli – do tej pory było to rozwiązywanie trwających wiele lat problemów schematu bazy danych. Oto krótki przykład:

`news/models.py`

    from django.db import models

    class Reporter(models.Model):
        full_name = models.CharField(max_length=70)

        def __str__(self):
            return self.full_name

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

        def __str__(self):
            return self.headline

## Zainstaluj

Następnie uruchom narzędzia linii poleceń Django, aby automatycznie stworzyć tabele w bazie danych:

/ 

    $ python manage.py makemigrations
    $ python manage.py migrate

    ...\> py manage.py makemigrations
    ...\> py manage.py migrate

Komenda `makemigrations` sprawdza wszystkie dostępne modele pod kątem tabel w bazie danych, które jeszcze nie istnieją. `migrate` uruchamia migracje i tworzy tabele w bazie danych oraz opcjonalnie daje :doc:` o wiele bogatszą kontrolę nad schematem </topics/migrations>`.

## Ciesz się wolnym API

Przez wolne i bogate pythonowe API masz dostęp do swoich danych. API jest tworzone w locie, nie wymaga generowania kodu:

    # Import the models we created from our "news" app
    >>> from news.models import Article, Reporter

    # No reporters are in the system yet.
    >>> Reporter.objects.all()
    <QuerySet []>

    # Create a new Reporter.
    >>> r = Reporter(full_name="John Smith")

    # Save the object into the database. You have to call save() explicitly.
    >>> r.save()

    # Now it has an ID.
    >>> r.id
    1

    # Now the new reporter is in the database.
    >>> Reporter.objects.all()
    <QuerySet [<Reporter: John Smith>]>

    # Fields are represented as attributes on the Python object.
    >>> r.full_name
    'John Smith'

    # Django provides a rich database lookup API.
    >>> Reporter.objects.get(id=1)
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__startswith="John")
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__contains="mith")
    <Reporter: John Smith>
    >>> Reporter.objects.get(id=2)
    Traceback (most recent call last):
        ...
    DoesNotExist: Reporter matching query does not exist.

    # Create an article.
    >>> from datetime import date
    >>> a = Article(
    ...     pub_date=date.today(), headline="Django is cool", content="Yeah.", reporter=r
    ... )
    >>> a.save()

    # Now the article is in the database.
    >>> Article.objects.all()
    <QuerySet [<Article: Django is cool>]>

    # Article objects get API access to related Reporter objects.
    >>> r = a.reporter
    >>> r.full_name
    'John Smith'

    # And vice versa: Reporter objects get API access to Article objects.
    >>> r.article_set.all()
    <QuerySet [<Article: Django is cool>]>

    # The API follows relationships as far as you need, performing efficient
    # JOINs for you behind the scenes.
    # This finds all articles by a reporter whose name starts with "John".
    >>> Article.objects.filter(reporter__full_name__startswith="John")
    <QuerySet [<Article: Django is cool>]>

    # Change an object by altering its attributes and calling save().
    >>> r.full_name = "Billy Goat"
    >>> r.save()

    # Delete an object with delete().
    >>> r.delete()

## Dynamiczny interfejs administracyjny: to nie tylko rusztowanie – to cały dom

Gdy twoje modele są już zdefiniowane, Django może automatycznie stworzyć profesjonalny, gotowy na produkcję interfejs administracyjny – witrynę, która pozwala uwierzytelnionym użytkownikom dodawać, zmieniać i usuwać obiekty. Jedynym wymaganym krokiem jest rejestracja modelu w witrynie administracyjnej:

`news/models.py`

    from django.db import models

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

`news/admin.py`

    from django.contrib import admin

    from . import models

    admin.site.register(models.Article)

Filozofia tutaj jest następująca: twoja strona jest edytowana przez obsługę, klienta lub może po prostu ciebie – i nie chcesz musieć tworzyć backendowych interfejsów jedynie do zarządzania treścią.

Jednym z typowych workflow w tworzeniu aplikacji Django jest stworzenie modelu i uruchomienie administracji tak szybko jak to możliwe, aby obsługa (lub klienci) mogli zacząć uzupełniać dane. Następnie, skupienie się na sposobie prezentacji tych danych odbiorcom.

## Zaprojektuj swoje URL-e

Prosty, elegancki schemat URL-i jest ważnym detalem w wysokiej jakości aplikacji webowej. Django wspiera piękne projekty URL i nie dodaje żadnych wstawek do URL-i, typu `.php` lub `.asp`.

Aby zaprojektować URL-e dla aplikacji, tworzysz moduł Pythona zwany URLconf. Spis treści dla twojej aplikacji, zawiera mapowanie pomiędzy wzorcami URL i pythonowymi funkcjami callback. Pliki URLconf służą również do oddzielania URL-i z kodu Python.

Tak mógłby wyglądać URLconf dla powyższego przykładu `Reporter`/`Article`:

`news/urls.py`

    from django.urls import path

    from . import views

    urlpatterns = [
        path("articles/<int:year>/", views.year_archive),
        path("articles/<int:year>/<int:month>/", views.month_archive),
        path("articles/<int:year>/<int:month>/<int:pk>/", views.article_detail),
    ]

Kod powyżej mapuje ścieżki URL do pythonowych funkcji callback („widoków”). Ciągi znaków ścieżek używają parametrowych tagów, aby „zebrać” wartości z URL-i. Gdy użytkownik żąda strony, Django przelatuje przez wszystkie ścieżki, po kolei, i zatrzymuje się na pierwszej, która spełnia żądany URL. (Jeśli żadna z nich nie pasuje, Django wywołuje specjalny widok 404.) Działa to niesamowicie szybko, gdyż ścieżki są kompilowane do wyrażeń regularnych w czasie ładowania.

Gdy któryś z wzorców URL pasuje, Django wywołuje podany widok, który jest pythonową funkcją. Każdy widok dostaje w parametrze obiekt „request” – który zawiera metadane żądania – i wartości zebrane we wzorcu.

Na przykład, jeśli użytkownik zażądałby URL-a „/articles/2005/05/39323/”, Django wywołałoby funkcję `news.views.article_detail(request, year=2005, month=5, pk=39323)`.

## Napisz swoje widoki

Każdy widok jest odpowiedzialny za zrobienie jednej z dwóch rzeczy: Zwrócenie obiektu `HttpResponse` zawierającego treść dla żądanej strony lub rzucenie wyjątku takiego jak `Http404`. Reszta zależy od ciebie.

W ogólności, widok pobiera dane stosowne do parametrów, ładuje szablon i renderuje go z pobranymi danymi. Tutaj jest przykładowy widok dla `year_archive` z powyżej:

`news/views.py`

    from django.shortcuts import render

    from .models import Article

    def year_archive(request, year):
        a_list = Article.objects.filter(pub_date__year=year)
        context = {"year": year, "article_list": a_list}
        return render(request, "news/year_archive.html", context)

Ten przykład wykorzystuje system szablonów Django, który ma kilka potężnych funkcji, ale stara się pozostać wystarczająco prosty w użyciu dla nie-programistów.

## Zaprojektuj swoje szablony

Kod powyżej ładuje szablon `news/year_archive.html`.

Django ma ścieżkę wyszukiwania szablonów, która pozwala ci minimalizować redundancję pomiędzy szablonami. W swoich ustawieniach Django podajesz listę katalogów do szukania w nich szablonów z `DIRS`. Jeśli szablon nie istnieje w pierwszym katalogu, sprawdzany jest drugi i tak dalej.

Powiedzmy, że szablon `news/year_archive.html` został odnaleziony. Tak mógłby wyglądać:

`news/templates/news/year_archive.html`

    {% extends "base.html" %}

    {% block title %}Articles for {{ year }}{% endblock %}

    {% block content %}
    <h1>Articles for {{ year }}</h1>

    {% for article in article_list %}
        <p>{{ article.headline }}</p>
        <p>By {{ article.reporter.full_name }}</p>
        <p>Published {{ article.pub_date|date:"F j, Y" }}</p>
    {% endfor %}
    {% endblock %}

Zmienne są otoczone podwójnymi nawiasami klamrowymi. `{{ article.headline }}` znaczy „wypisz wartość atrybutu »headline« artykułu”. Ale kropki nie są używane tylko do odwoływania się do atrybutów. Mogą one być odwołaniami do klucza w słowniku, do indeksu tablicy i wywołaniami funkcji.

Zwróć uwagę, że `{{ article.pub_date|date:"F j, Y" }}` używa uniksowego „pipe” (znak „|”). Jest on nazywany filtrem szablonu i jest sposobem na przefiltrowanie wartości zmiennej. W tym przypadku filtr „date” formatuje pythonowy obiekt datetime do żądanego formatu (tak jak w funkcji „date” w PHP).

Możesz układać w łańcuchy tyle filtrów, na ile masz ochotę. Możesz napisać własne filtry szablonów, które uruchamiają pod spodem własny kod Pythona.

I na koniec, Django wykorzystuje koncept „dziedziczenia szablonów”. To to co robi `{% extends "base.html" %}`. To znaczy „najpierw załaduj szablon nazwany »base«, który definiuje zestaw bloków i wypełnij te bloki poniższymi blokami”. W skrócie, pozwoli to drastycznie wyciąć powtórzenia w szablonach: każdy szablon musi definiować tylko to, co jest dla niego unikalne.

Tak może wyglądać szablon „base.html”, wliczając użycie plików statycznych:

`templates/base.html`

    {% load static %}
    <html lang="en">
    <head>
        <title>{% block title %}{% endblock %}</title>
    </head>
    <body>
        <img src="{% static 'images/sitelogo.png' %}" alt="Logo">
        {% block content %}{% endblock %}
    </body>
    </html>

Prostszymi słowami, definiuje on look-and-feel strony (z logiem strony) i zawiera „dziury” do wypełnienia przez szablony-dzieci. To powoduje, że redesign strony można zrobić zmieniając jeden plik – szablon bazowy.

Pozwala ci także stworzyć wiele wersji strony, z różnymi szablonami bazowymi, w czasie gdy wykorzystujesz te same szablony-dzieci. Twórcy Django użyli tej techniki, by stworzyć kompletnie inne mobilne wersje stron – jedynie przez stworzenie nowych szablonów bazowych.

Zwróć uwgę, że nie musisz używać systemu szablonów Django jeśli wolisz inny system. Pomimo że system szablonów Django jest szczególnie dobrze zintegrowany z warstwą modelu Django, nic nie zmusza cię do jego używania. Tak naprawdę nie musisz używać też bazodanowego API Django. Możesz użyć inną warstwę abstrakcji bazy danych, możesz czytać pliki XML, możesz czytać pliki z dysku lub cokolwiek co chcesz. Każdy kawałek Django – modele, widoki, szablony – jest rozdzielony od następnego.

## To tylko powierzchnia

To był tylko szybki przegląd funkcjonalności Django. Niektóre bardziej przydatne funkcje:

- Framework cache’owania, który integruje się z Memcached lub innymi back-endami.

- Framework syndykacyjny, który pozwala stworzyć feedy RSS i Atom przez napisanie małej klasy w Pythonie.

- Bardziej atrakcyjne automatycznie wygenerowane funkcje panelu administracyjnego – ten przegląd ledwo musnął powierzchnię.

Następne kroki to pobranie Django, przeczytanie tutoriala i dołączenie do społeczności. Dziękujemy za zainteresowanie!