Tworzenie pierwszej aplikacji Django, część 2

Ta część tutoriala zaczyna się w miejscu, w którym skończyła się część pierwsza. Będziemy kontynuować budowę aplikacji webowej - sondy - i skupimy się na automatycznie generowanym panelu administracyjnym.

Aktywacja panelu administracyjnego

Część administracyjna Django jest domyślnie wyłączona - można ją opcjonalnie włączyć. Aby to zrobić dla swojej instalacji, trzeba wykonać trzy kroki:

• dodać “django.contrib.admin” do ustawień INSTALLED_APPS;
• wykonać komendę django-admin.py install admin. To spowoduje utworzenie dodatkowych tablic w bazie danych.
• poprawić plik myproject.urls i odkomentować linię znajdującą się pod linią “Uncomment this for admin:”. Ten plik jest plikiem konfiguracyjnym dla URLi Twojej strony - będziemy zgłębiać jego tajniki w następnej części tutoriala. Na tą chwilę wystarczy Ci wiedzieć, że rzutuje on adresy URL na Twoją aplikację.

Tworzenie konta użytkownika

Wykonaj poniższe polecenie aby stworzyć konto administracyjne Twoim panelu:

django-admin.py createsuperuser --settings=myproject.settings

Skrypt zapyta się Ciebie o nazwę użytkownika, adres e-mail oraz hasło (dwa razy).

Uruchomienie serwera testowego

Aby ułatwić niektóre rzeczy, Django dostarcza bazujący na bibliotece BaseHTTPServer (dołączanej do Pythona) serwer WWW. Spróbujmy uruchomić go i zacznijmy poznawanie panelu administracyjnego.

Uruchom poniższą komendę:

django-admin.py runserver --settings=myproject.settings

To spowoduje uruchomienie lokalnego serwera nasłuchującego domyślnie na porcie 8000. Jeśli chcesz zmienić port serwera, dodaj do ostatniego polecenia dodatkowy argument:

django-admin.py runserver 8080 --settigs=myproject.settings

Nie używaj wbudowanego w Django serwera w środowisku produkcyjnym. Jego przeznaczeniem jest tylko i wyłącznie pomoc podczas trakcie testów i pisania aplikacji.

Teraz uruchom przeglądarkę i przejdź do ‘podkatalogu’ /admin/ swojej lokalnej domeny - np. 127.0.0.1:8000/admin. Powinieneś zobaczyć ekran logowania:

Panel administracyjny

Spróbuj teraz się zalogować. Powinieneś ujrzeć stronę główną panelu adminiatrcyjnego Django:

Początkowo powinieneś zobaczyć dwie części które możesz poddać edycji: grupy i użytkowników. To jest podstawowa funkcjonalność Django dostarczana domyślnie.

Modyfikacja sondy z poziomu admina

Ale gdzie jest nasza sonda? Nie ma jej przecież w panelu administracyjnym.

Trzeba zrobić jedną rzecz: ‘poinformować’ Django że nasz model polls.Poll powinien posiadać interfejs do zarządzania nim. Wyedytuj plik myproject/apps/polls/models/polls.py i dodaj tam klasę wewnętrzą META z atrybutem admin:

class Poll(meta.Model):
  # ...
  class META:
    admin = meta.Admin()

Klasa META zawiera wszystkie meta dane nie będące polami bazy danych o tym modelu.

Teraz przeładuj stronę administracyjną Django abyś mógł zobaczyć zmiany. Zwróć uwagę, że nie musiałeś restartować serwera Django - on sam zauważył, że zmieniły się ustawienia i przeładował kod.

Badanie funkcjonalności admina

Zauważ że model Poll posiada atrybut admin dzięki któremu Django wie, że ma wyświetlić go w panelu:

Kliknij “Polls”. Jesteś teraz na wykazie wszystkich sond. Ta strona pokazuje wszystkie sondy znajdujące się w bazie danych i pozwala wybrać jedną z nich do edycji. Teraz znajduje się tam tylko “What’s up?” - czyli sonda którą utworzyliśmy w pierwszej części tutoriala:

Kliknij “What’s up?” aby poddać ją edycji:

Rzeczy które warto zauważyć:

• formularz został wygenerowany automatycznie na podstawie informacji z modelu sondy (Poll);
• różnym rodzajom pól modelu (meta.DateTimeField, meta.CharField) odpowiadają różne kontrolki HTML. Każdy typ pola wie jak ma zostać wywietlony w panelu administracyjnym;
• do każdego pola DateTimeField dodawane są dodatkowe przyciski. Dla daty jest to “Today” (”Dziś”) wraz z przyciskiem wyświetlającym okienko z mini kalendarzem, natomiast dla pola “Time” (”Czas”) są przypisane przyciski “Now” (”Teraz”) oraz drugi, służący do pokazania okienka z listą najczęściej używanych określeń czasu.

Dolna część strony daje kilka opcji:

• Save - zapisuje zmiany i wraca do listy obiektów danego rodzaju;
• Save and continue editing - zapisuje zmiany i przeładowuje stronę;
• Save and add another - zapisuje zmiany i przenosi do nowego, pustego formularza odpowiedniego dla danego rodzaju obiektu;
• Delete - wyświetla ekran potwierdzający usunięcie obiektu.

Zmień datę publikacji (”Date published”) sondy poprzez kliknięcie skrótów “Today” i “Now”. Następnie kliknij “Save and continue editing”. Teraz wybierz “History” (”Historia”) w prawym górnym rogu strony. Zobaczysz listę zmian dla tego obiektu dokonanych w panelu administracyjnym Django, wraz z datą i godziną zmiany oraz loginem osoby dokonującej tą zmianę:

Dostosowywanie panelu administracyjnego

Take a few minutes to marvel at all the code you didn’t have to write.

Poprawmy go nieco. Możemy zmienić kolejność pól poprzez dodanie parametru field do meta.Admin:

admin = meta.Admin(
  fields = (
    (None, {'fields': ('pub_date', 'question')}),
  ),
)

To spowodowało przesunięcie pola “Pub date” na górę:

Nie ma to większego znaczenia przy tylko dwóch polach, jednak dla formularzy z większą ilością pól ustawienie intuicyjnej kolejności jest ważne ze względów używalności takiego formularza.

A skoro już mówimy o formularzach z większą ilością pól, możesz chcieć je podzielić na zestawy:

admin = meta.Admin(
  fields = (
    (None, {'fields': ('question',)}),
    ('Date information', {'fields': ('pub_date',)}),
  ),
)

Pierwszym elementem w każdej tupli (krotce) w atrybucie fields jest nazwa zestawu. Teraz formularz wygląda tak:

Możesz przypisać do każdego zestawu konkretną klasę języka HTML. Django posiada wbudowaną obsługę klasy “collapse” która wyświetla wybrany zestaw pól jako początkowo zwinięte. Jest to użyteczne gdy mamy długi formularz z kilkoma polami które są rzadziej używane:

admin = meta.Admin(
  fields = (
    (None, {'fields': ('question',)}),
    ('Date information', {
      'fields': ('pub_date',), 'classes': 'collapse'}),
  ),
)

Dodawanie obiektów powiązanych

Ok. Mamy już w panelu nasze sondy. Ale każda sonda (Poll) ma kilka odpowiedzi (Choices), a w panelu nie są one wyświetlane.

Są 2 sposoby na naprawienie tego problemu. Pierwszym jest dodanie modelowi Choice jego własnego atrybutu admin, tak samo jak zrobiliśmy to z modelem Polls. Tak by to wyglądało:

class Choice(meta.Model):
  # ...
  class META:
    admin = meta.Admin()

Teraz odpowiedzi do sondy są dostępne w panelu. Formularz dodawania odpowiedzi (”Add choice”) wygląda tak:

W powyższym formularzu pole “Poll” jest polem wyboru zawierającym wszystkie sondy w bazie. W naszym przypadku, tylko jedna sonda chwilowo została zapisana.

Zobacz także odnośnik “Add another” (”Dodaj inną”) znajdujący się obok pola “Poll”. Każdy obiekt powiązany kluczem obcym (ForeignKey) z innym obiektem dostaje taki link automatycznie. Jeśli klikniesz “Add another”, zobaczysz okienko (popup) z formularzem do dodawania sond. Jeśli dodasz nową sondę za pomocą tego okienka i klikniesz “Save”, Django zapisze nową sondę w bazie danych oraz uaktualni pole wyboru znajdujące się w formularzu odpowiedzi (”Choice”).

Powyższy sposób nie jest najbardziej efektywną metodą dodawania obiektów odpowiedzi do systemu. Byłoby wygodniej, jeśli mógłbyś dodawać odpowiedzi do sondy bezpośrednio z formularza w którym tworzysz nową sondę. Skoro tak, to spróbujmy to wykonać.

Usuń atrybut admin z modelu Choice. Następnie zmień pole klucza obcego w obiekcie Choice:

poll = meta.ForeignKey(Poll,
  edit_inline=meta.STACKED,
  num_in_admin=3)

Powyższa zmiana informuje Django: “Obiekty odpowiedzi są edytowane z poziomu formularza sond. Domyślnie dostarcz 3 zestawy pól odpowiedzi.“.

Zmieńmy teraz pola w obiekcie Choice i dodajmy tam core=True:

choice = meta.CharField(maxlength=200, core=True)
votes = meta.IntegerField(core=True)

To mówi Django: “Kiedy edytujesz odpowiedzi w formularzu edycji sondy, pola ‘choice’ i ‘votes’ są wymagane. Wypełnienie któregokolwiek z nich oznacza że ma zostać dodany nowy obiekt odpowiedzi, a wyczyszczenie obydwóch pól oznacza usunięcie istniejącego obiektu.“.

Załaduj stronę “Add poll” żebyśmy mogli sprawdzić jak to wygląda:

Jak to działa: są tam 3 pola odpowiedzi - jak zostało ustalone przez opcję num_in_admin - ale za każdym razem gdy wrócisz do strony już stworzonego obiektu, dostaniesz kolejne pole odpowiedzi (tzn. nie ma na sztywno ustawionego ograniczenia co do ilości powiązanych obiektów które można dodać). Jeśli chcesz otrzymywać za każdym razem trzy nowe pola na odpowiedzi, musisz użyć parametru num_extra_on_change=3.

Jest tylko jeden mały problem: wyświetlenie wszystkich powiązanych wpisów zabiera mnóstwo miejsca na ekranie. Z tego powodu, Django pozwala na inny sposób wyświetlenia wewnętrznie powiązanych obiektów:

poll = meta.ForeignKey(Poll,
  edit_inline=meta.TABULAR,
  num_in_admin=3)

Z edit_inline=meta.TABULAR zamiast meta.STACKED obiekty dowiązane wyświetlane są w bardziej kompaktowy, tabelkowy sposób:

Modyfikacja listy obiektów

Teraz, kiedy strony edycji i dodawania sondy wyglądają tak jak powinny, spróbujmy poprawić stronę z listą sond.

Tutaj możesz sprawdzić jak to wygląda obecnie:

Domyślnie, Django pokazuje reprezentację repr() każdego obiektu. Oczywiście można to trochę dostosować, tak, żeby wyświetlał pożądane przez nas pola. Aby to zrobić, użyj opcji list_display, która jest krotką zawierającą nazwy pól do wyświetlenia jako kolumny na stronie z listą sond:

class Poll(meta.Model):
  # ...
  class META:
    admin = meta.Admin(
      # ...
      list_display = ('question', 'pub_date'),
    )

Dla sprawdzenia jak się sprawuje ta opcja, dodajmy tam naszą metodę was_published_today z pierwszej części tutoriala:

list_display = ('question', 'pub_date', 'was_published_today'),

Teraz nasza strona z listą sond wygląda tak:

Możesz kliknąć na nagłówku każdej z kolumn aby posortować listę sond po określonym parametrze - nie dotyczy to koluny “was_published_today”, ponieważ sortowanie z użyciem własnych metod nie jest obsługiwane przez Django. Zauważ też że nagłówek kolumny dla pola was_published_today jest domyślnie nazwą danej metody (z podkreślnikami zamienionymi na spacje). Można to też zmienić poprzez dodanie atrybutu short_description dla danej metody:

def was_published_today(self):
  return self.pub_date.date() == datetime.date.today()
was_published_today.short_description = 'Published today?'

Teraz dodajmy kolejne usprawnienia do naszej listy: filtry (”Filters”). Dodaj następującą linię do Poll.admin:

list_filter = ['pub_date'],

To spowodowało pojawienie się panelu bocznego “Filter” który pozwala na filtrowanie listy sond po polu pub_date:

Rodzaj wyświetlanych filtrów zależy od rodzaju pola po którym chcemy filtrować. Ponieważ pub_date jest polem typu DateTimeField, Django wie że potrzebne będą opcje “Any date” (”Każda data”), “Today” (”Dzisiaj”), “Past 7 days” (”Ostatnie siedem dni”), “This month” (”Ten miesiąc”), “This year” (”Ten rok”).

Zaczyna wyglądać coraz lepiej. Dodajmy możliwość wyszukiwania:

search_fields = ['question'],

Na górze strony pojawiło się teraz pole wyszukiwarki. Gdy zostanie tam wpisana jakaś fraza, Django przeszuka pola question. Możesz użyć tylu pól ile potrzebujesz - aczkolwiek pamiętaj, że Django używa tutaj kwerendy SQL LIKE, więc umieszczaj tu tylko te pola których potrzebujesz.

Na koniec, ponieważ nasza sonda posiada daty, powinniśmy pogrupować nasze sondy po tym właśnie polu. Dodaj poniższą linijkę:

date_hierarchy = 'pub_date',

Teraz na górze strony pojawiły się pola ułatwiające nawigację po dacie. Na samej górze pokazane są dostępne lata. Później miesiące i dni.

Pozostało mi jeszcze poinformować Ciebie, że lista sond jest automatycznie dzielona na strony mieszczące domyślnie do 50 obiektów. Stronicowanie listy sond, pole wyszukiwarki, filtry, grupowanie po datach i sortowanie po kolumnach wspópracują ze sobą tak jak tego oczekujesz.

Upiększanie panelu administracyjnego

Tak naprawdę, napisy “Django administration” i “example.com” na górze każdej strony są nieco mylące. To są tylko “wypełniacze”.

Bardzo łatwo jest je zmienić korzystając z systemu szablonów Django. Panel administracyjny Django jest tworzony przez samo Django, więc nic dziwnego że korzysta ze swojego własnego systemu szablonów.

Otwórz swój plik ustawień (myproject/settings.py) i spójrz na opcję TEMPLATE_DIRS. Jest to krotka, przechowywująca ścieżki do katalogów które Django ma sprawdzać w poszukiwaniu szablonów.

Domyślnie TEMPLATE_DIRS jest puste. Dodajmy tam linię aby poinformować Django gdzie ma szukać szablonów:

TEMPLATE_DIRS = (
  "/home/mytemplates", # Dopasuj tą linię do swoich potrzeb.
)

Skopiuj teraz plik admin/base_site.html z domyślnego katalogu szablonów Django (django/contrib/admin/templates) do podkatalogu admin w którymkolwiek z katalogów które ustawiłeś w TEMPLATE_DIRS. Na przykład jeśli umieściłeś w TEMPLATE_DIRS linijkę /home/mytemplates, jak powyżej, to skopiuj django/contrib/admin/templates/admin/base_site.html do katalogu /home/mytemplates/admin/base_site.html.

Teraz wystarczy wyedytować skopiowany plik zastępując domyślne teksty Django swoimi.

Zauważ, że każdy domyślny szablon Django może zostać nadpisany. Aby to zrobić, zrób dokładnie to samo co zrobiłeś przed chwilą z base_site.html - skopiuj go z domyślnego katalogu do swojego, i wykonaj zmiany.

Uważni czytelnicy mogą zapytać: ale jeśli TEMPLATE_DIRS był domyślnie pusty, jak Django wyszukiwał domyślne szablony do panelu administracyjnego ? Odpowiedź: domyślnie, Django automatycznie szuka w podkatalogu templates/ każdej aplikacji. Zajrzyj do loader types documentation żeby dowiedzieś się więcej.

Zmiana wyglądu listy projektów

Kontynuując temat zmian wyglądu, możesz także dostosować dla siebie stronę z listą dostępnych aplikacji (indeks) panelu administracyjnego.

Domyślnie pokazywane są wszystkie dostępne aplikacje, zgodnie z Twoimi ustawieniami INSTALLED_APPS. Ale kolejność, w jakiej są wyświetlane, jest losowa, a Ty możesz sobie zażyczyć konkretnego wyglądu tejże strony. Poza tym, indeks jest prawdopodobnie najważniejszą częścią panelu, więc powinien być prosty w użyciu.

Szablon który tutaj użyjemy to admin/index.html (wykonaj te same czynności co przy admin/base_site.html w poprzedniej sekcji - skopiuj go z katalogu domyślnego do swojego). Następnie wyedytuj ten plik - zobaczysz że jest w nim użyty tag {% get_admin_app_list as app_list %}. Jest to coś, co zwraca listę zainstalowanych aplikacji Django. Zamiast używać tego taga, możesz wstawić “na sztywno” odnośniki do konkretnych stron panelu odpowiedzialnych za konkretne obiekty - i ułożyć je tak jak uważasz że będzie najlepiej.

Django pozwala też na użycie pewnego skrótu w tym temacie. Wykonaj polecenie django-admin.py adminindex polls aby dostać cały kod szablonu który należy umieścić w szablonie indeksu. Jest to na początku bardzo przydatne.

Aby dowiedzieć się więcej o dostosowywaniu wyglądu panelu administracyjnego Django, zajrzyj na Django admin CSS guide.

Kiedy już poznasz panel administracyjny Django, przeczytaj trzecią część tego tutoriala aby zacząć tworzyć publicznie widoczną stronę aplikacji.