This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Django (klasycznie): instrukcja pracy na przykładzie „Aktualności”

Ta strona jest krótką, praktyczną ściągą do pracy z Django w wariancie klasycznym: backend + szablony (Django Templates). Odwołuje się do przykładu z repozytorium: projekt config i aplikacja news.

Spis treści

• 1. Jak uruchomić projekt
• 2. Jak czytać strukturę projektu
• 3. Dane: modele i migracje
• 4. Widoki, routing i szablony
• 5. Panel administratora (CMS)
• 6. Rozwój projektu: typowe zadania
• 7. Dobre praktyki (minimum produkcyjne)
• 8. Checklist „dodaj nową funkcję”
• 9. Najczęstsze problemy

---

1. Jak uruchomić projekt

Wymagania

• Python 3.8+
• (Zalecane) środowisko wirtualne venv

Instalacja i start

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

Adresy:

• Front: http://127.0.0.1:8000/
• Admin: http://127.0.0.1:8000/admin/

Superuser (admin)

python manage.py createsuperuser

---

2. Jak czytać strukturę projektu

Django składa się z:

• Projektu (tu: katalog config) – konfiguracja systemu (ustawienia, główne URL-e, WSGI/ASGI)
• Aplikacji (tu: katalog news) – moduł domenowy (modele, widoki, szablony, admin)

Najważniejsze pliki

• manage.py – wejście do narzędzi Django (runserver, migrate, itp.)
• config/settings.py – globalne ustawienia
• config/urls.py – główny routing
• news/models.py – modele bazy danych (ORM)
• news/views.py – logika prezentacji (np. ListView, DetailView)
• news/urls.py – routing aplikacji news
• news/templates/ – szablony HTML

Dlaczego config, a nie nazwa projektu jak w kreatorze IDE?

Nazwanie katalogu konfiguracyjnego config upraszcza pracę (unikasz sytuacji „folder projektu” i „folder konfiguracji” o tej samej nazwie). To szczególnie pomaga, gdy wraca się do projektu po czasie albo przejmuje po kimś repozytorium.

apps.py (czyli „przedstawienie się” aplikacji)

Każda aplikacja ma konfigurację w news/apps.py (tu: klasa NewsConfig). W nowoczesnym Django jest to standardowy punkt, w którym aplikacja:

• deklaruje nazwę (name = "news")
• może dostać przyjazną nazwę do admina (verbose_name)
• może uruchomić kod startowy w ready() (np. rejestracja sygnałów)

W INSTALLED_APPS można wpisać:

• prosto: 'news'
• w pełni konfigurowalnie: 'news.apps.NewsConfig' (zalecane, jeśli używasz verbose_name albo ready())

---

3. Dane: modele i migracje

Model = tabela w bazie

Modele definiuje się w news/models.py. Przykład (uproszczony opis):

• title – tytuł
• content – treść
• is_active – czy publikować
• created_at, updated_at – daty

Migracje (obowiązkowe po zmianach modeli)

Po każdej zmianie w models.py:

python manage.py makemigrations
python manage.py migrate

Jak dodać pole do modelu (przykład)

1. Dodaj pole w modelu, np.:

• slug (adres URL)
• image (obrazek)
• category (relacja do kategorii)

2. Wykonaj migracje:

python manage.py makemigrations
python manage.py migrate

3. Jeśli pole ma być w adminie – zaktualizuj news/admin.py.

---

4. Widoki, routing i szablony

Widoki (CBV) w przykładzie

W news/views.py użyte są Class-Based Views:

• NewsListView – lista aktualności
• NewsDetailView – szczegóły

Ważny element: filtrowanie po is_active=True (treści nieaktywne nie są widoczne na froncie).

Routing URL

• config/urls.py podpina aplikację:
  • path('', include('news.urls'))
• news/urls.py mapuje widoki:
  • '' → lista
  • '<int:pk>/' → szczegóły

Szablony

• news/templates/base.html – layout bazowy
• news/templates/news/news_list.html – lista
• news/templates/news/news_detail.html – szczegóły

Mechanizm dziedziczenia:

• news_list.html i news_detail.html używają {% extends 'base.html' %}
• treść idzie w {% block content %}

---

5. Panel administratora (CMS)

Panel admina w Django to najszybszy sposób na „dynamiczną podmianę treści”:

• dodawanie / edycja / usuwanie wpisów
• ustawianie is_active (publikacja)

Konfiguracja admina jest w news/admin.py:

• list_display – kolumny w liście
• search_fields – wyszukiwarka
• list_filter – filtry boczne
• list_editable – szybka edycja w tabeli

---

6. Rozwój projektu: typowe zadania

A) Dodanie paginacji na liście

W ListView:

• dodaj paginate_by = 10 W szablonie dopisz linki „poprzednia/następna”.

B) Przyjazne URL-e (slug)

1. Dodaj slug do modelu (unikalny)
2. Zmień URL:

• path('<slug:slug>/', ...)

3. Zmień DetailView:

• slug_field = 'slug', slug_url_kwarg = 'slug'

4. W adminie automatyzuj slug:

• prepopulated_fields = {"slug": ("title",)}

C) Formularze (np. komentarze / kontakt)

1. Utwórz forms.py i forms.ModelForm
2. W widoku obsłuż GET (formularz) i POST (walidacja + zapis)
3. W szablonie dodaj {% csrf_token %}

D) Pliki statyczne (CSS/JS)

Minimalnie:

• trzymać CSS w static/
• w szablonie:
  • {% load static %}
  • <link rel="stylesheet" href="{% static '...' %}">

E) Upload plików (MEDIA: obrazki do aktualności)

1. Dodaj ImageField i doinstaluj Pillow:

pip install Pillow

2. Dodaj w settings.py:

• MEDIA_URL, MEDIA_ROOT

3. W urls.py w trybie dev dodaj obsługę media.

---

7. Dobre praktyki (minimum produkcyjne)

• Nie publikuj SECRET_KEY i DEBUG=True w środowisku produkcyjnym.
• Trzymaj konfigurację w zmiennych środowiskowych (.env / systemowe ENV).
• Waliduj dane wejściowe (formularze) i unikaj logiki „w szablonach”.
• Rozdzielaj odpowiedzialności:
  • model: dane i reguły domenowe
  • widok: przepływ i logika prezentacji
  • szablon: wyświetlanie
• Przy rozbudowie o więcej modułów: twórz kolejne aplikacje (np. gallery, accounts), a nie „wrzucaj wszystkiego” do news.

requirements.txt (pinowanie zależności)

W repozytorium warto trzymać plik requirements.txt z konkretnymi wersjami bibliotek. Dzięki temu:

• każdy uruchamia projekt na tych samych wersjach,
• łatwiej odtworzyć środowisko po czasie,
• wdrożenia i CI są powtarzalne.

Instalacja zależności:

pip install -r requirements.txt

Aktualizacja pliku po dołożeniu nowych paczek:

pip freeze > requirements.txt

Zalecany workflow w zespole:

1. venv + aktywacja
2. pip install -r requirements.txt
3. praca nad projektem
4. jeśli doszły nowe biblioteki: pip freeze > requirements.txt i commit requirements.txt

---

8. Checklist „dodaj nową funkcję”

1. Zmiana danych?

• models.py → makemigrations → migrate

2. Nowy ekran / endpoint?

• views.py (widok)
• urls.py (routing)
• templates/ (szablon)

3. Ma być edytowalne z admina?

• admin.py (rejestracja + konfiguracja listy)

4. Dochodzi formularz?

• forms.py + POST + {% csrf_token %}

5. Weryfikacja:

python manage.py check
python manage.py runserver

---

9. Najczęstsze problemy

„No module named …” / nie widzi aplikacji

• sprawdź INSTALLED_APPS w config/settings.py
• upewnij się, że uruchamiasz projekt z poprawnego środowiska (source venv/bin/activate)

Zmieniłem model i nie działa

• brak migracji:

python manage.py makemigrations
python manage.py migrate

404 na stronie szczegółów

• sprawdź, czy wpis ma is_active=True
• sprawdź dopasowanie URL (pk/slug) i linkowanie w szablonach

Admin nie pokazuje zmian

• odśwież stronę / sprawdź rejestrację modelu w admin.py
• upewnij się, że migrowałeś bazę po zmianach w modelu