====== Opcje pól w modelach ======


===== null =====

Opcja ''null'' w polach modeli Django jest używana do określenia, czy pole w bazie danych może przyjmować wartości NULL. Wartością tej opcji jest wartość logiczna (''True'' lub ''False''). Opcja ta ma wpływ na to, czy w kolumnie bazy danych dla danego pola może być zapisane NULL (brak wartości).\\
\\
Oto kilka przypadków użycia opcji ''null'':

==== Pole, które może być puste ====

<code python>
class MyModel(models.Model):
    description = models.TextField(null=True)
</code>

W tym przypadku pole ''description'' może przyjmować wartości NULL w bazie danych. Oznacza to, że w przypadku braku wartości dla tego pola, baza danych zapisze NULL.\\

==== Pole, które nie może być puste ====

<code python>
class AnotherModel(models.Model):
    age = models.IntegerField(null=False)
</code>

W tym przypadku pole ''age'' nie może przyjmować wartości NULL w bazie danych. Domyślnie, gdy ''null'' nie jest ustawione explicite na ''True'', pola są tak skonfigurowane, aby nie przyjmować wartości NULL.\\
\\
Opcja ''null'' jest szczególnie istotna, gdy definiujesz strukturę bazy danych. Jeśli ''null=True'', oznacza to, że kolumna dla tego pola w bazie danych może przechowywać wartości NULL, co może być przydatne, gdy nie masz danych do wprowadzenia, ale chcesz zachować spójność struktury bazy danych.\\
\\
Warto zauważyć, że ''null'' dotyczy warstwy bazy danych, podczas gdy ''blank'' dotyczy formularzy i widoków Django. Oznacza to, że ustawienie ''null=True'' informuje system Django, że pole może przyjmować wartości NULL w bazie danych, ale nie wpływa na to, czy pole może być puste w formularzach.\\
\\
Przykład z użyciem ''null'' w połączeniu z ''blank'':

<code python>
class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField(blank=True, null=True)
</code>

W tym przypadku, ''null=True'' oznacza, że baza danych może przechowywać wartości NULL dla pola ''content'', a `blank=True` oznacza, że pole to może być puste w formularzach Django.
===== blank =====

Opcja ''blank'' w polach modeli Django jest używana do określenia, czy pole może być pozostawione puste (niezainicjowane) w przypadku tworzenia lub aktualizowania obiektu modelu. Opcja ta jest dostępna w wielu różnych typach pól modelu, takich jak ''CharField'', ''TextField'', ''DateField'', ''IntegerField'', itp.\\
\\
Wartości opcji ''blank'' to wartości logiczne (''True'' lub ''False''). Oto kilka przykładów użycia:

==== Dopuszczalne puste pole ====

<code python>
class MyModel(models.Model):
    name = models.CharField(max_length=100, blank=True)
</code>

W tym przykładzie pole ''name'' może być pozostawione puste. Podczas tworzenia lub aktualizacji obiektu modelu, nie będzie wymagane podanie wartości dla tego pola.

==== Pole nie może być puste ====

<code python>
class AnotherModel(models.Model):
    age = models.IntegerField(blank=False)
</code>

W tym przypadku pole ''age'' nie może być pozostawione puste. Podczas tworzenia lub aktualizacji obiektu modelu, konieczne będzie podanie wartości dla tego pola.\\
\\
Opcja ''blank'' jest zazwyczaj używana w połączeniu z opcją ''null'' oraz ''default'', a także może być istotna podczas definiowania formularzy w Django. Warto zauważyć, że ''blank'' dotyczy formularzy i widoków Django, podczas gdy ''null'' dotyczy bazy danych. Oznacza to, że ustawienie ''blank=True'' informuje system Django, że pole może być puste w formularzach, ale nie wpływa na to, czy baza danych dopuszcza wartości NULL dla tego pola.\\
\\
Przykład z użyciem ''blank'' w połączeniu z ''null'':

<code python>
class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField(blank=True, null=True)
</code>

W tym przypadku, ''blank=True'' oznacza, że pole ''content'' może być puste w formularzach, a ''null=True'' oznacza, że baza danych może przechowywać wartości NULL dla tego pola.

===== choices =====

Opcja ''choices'' w polach modeli Django jest używana do zdefiniowania zestawu predefiniowanych wartości, które mogą być używane jako możliwe wartości dla danego pola. Ta opcja jest szczególnie przydatna, gdy chcesz ograniczyć dopuszczalne wartości dla konkretnego pola do określonego zestawu. W połączeniu z ''CharField'', ''IntegerField'', lub innymi polami, ''choices'' pozwala określić, które wartości są dopuszczalne, a także dostarcza czytelnych etykiet dla tych wartości.\\
\\
Przykłady użycia opcji ''choices'':

==== Pole CharField z choices ====

<code python>
class MyModel(models.Model):
    GENDER_CHOICES = [
        ('M', 'Male'),
        ('F', 'Female'),
        ('O', 'Other'),
    ]

    gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
</code>

==== Pole IntegerField z choices ====

<code python>
class MyModel(models.Model):
    STATUS_CHOICES = [
        (0, 'Inactive'),
        (1, 'Active'),
        (2, 'Pending'),
    ]

    status = models.IntegerField(choices=STATUS_CHOICES)
</code>

==== Pole BooleanField z choices ====

<code python>
class MyModel(models.Model):
    AVAILABILITY_CHOICES = [
        (True, 'Available'),
        (False, 'Not Available'),
    ]

    is_available = models.BooleanField(choices=AVAILABILITY_CHOICES)
</code>

W powyższych przykładach ''choices'' składa się z listy krotek, gdzie każda krotka zawiera dwie wartości: pierwsza to wartość, która będzie przechowywana w bazie danych, a druga to czytelna etykieta, która będzie wyświetlana w interfejsie użytkownika.\\
\\
Korzyści z użycia ''choices'':\\
\\
- **Ograniczenie dopuszczalnych wartości:** Pozwala na zdefiniowanie ograniczonego zestawu możliwych wartości, co pomaga uniknąć błędów danych i utrzymać spójność danych w bazie danych.\\
\\
- **Poprawia czytelność kodu:** Etykiety dostarczają czytelnych opisów wartości, co ułatwia zrozumienie przeznaczenia danych pola.\\
\\
- **Ułatwia współpracę z formularzami:** W przypadku korzystania z formularzy Django, ''choices'' pomaga w automatycznym generowaniu pól wyboru (select fields) z odpowiednimi etykietami.\\
\\
- **Wspomaga zrozumienie modelu:** Pomaga w zrozumieniu i dokumentowaniu modelu, szczególnie w przypadku pól, które przyjmują określone i znane zestawy wartości.\\
\\
Ogólnie rzecz biorąc, ''choices'' jest używane w celu zdefiniowania i narzucenia ograniczeń na dopuszczalne wartości dla pól modelu w Django.\\
\\
Termin "Enumeration types" w kontekście Django może odnosić się do korzystania z specjalnego pola modelu ''EnumField'', wprowadzonego oficjalnie w Django 3.2 i nowszych. Wcześniej, przed pojawieniem się ''EnumField'', często stosowano pole ''CharField'' lub ''IntegerField'' z opcją ''choices'' do symulowania enumeracji.\\
\\
Różnice między stosowaniem ''choices'' a ''EnumField'' obejmują:

==== choices z CharField lub IntegerField ====

1. **Typ danych:** 
  * W przypadku ''choices'' z ''CharField'' lub ''IntegerField'', wartości są przechowywane w bazie danych jako znaki lub liczby całkowite.

2. **Predefiniowane wartości:**
  * ''choices'' opiera się na predefiniowanych zestawach wartości w postaci krotek.

3. **Elastyczność:**
  * Jest elastyczny i pozwala na używanie różnych typów pól (np. `CharField`, `IntegerField`) w zależności od potrzeb.

4. **Zakres wartości:**
  * Możesz używać różnych zakresów wartości w zależności od używanego pola.

5. **Dostępność przed Django 3.2:**
  * Jest dostępny w wersjach Django przed 3.2.

Przykład z ''choices'' i ''CharField'':

<code python>
class MyModel(models.Model):
    GENDER_CHOICES = [
        ('M', 'Male'),
        ('F', 'Female'),
        ('O', 'Other'),
    ]

    gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
</code>

==== EnumField ====

1. **Typ danych:**
  * Wartości są przechowywane jako specjalny typ enumeracyjny (typ wyliczeniowy), co może ułatwić operacje na danych.

2. **Definiowanie Enumeracji:**
  * Wymaga zdefiniowania specjalnej klasy ''Enum'' wewnątrz modelu, co pozwala na bardziej strukturalne definiowanie enumeracji.

3. **Predefiniowane wartości:**
  * Wartości są predefiniowane wewnątrz klasy Enum.

4. **Zakres wartości:**
  * Wszystkie możliwe wartości są zdefiniowane w jednym miejscu, co może pomóc w utrzymaniu spójności.

5. **Dostępność od Django 3.2:**
  * ''EnumField'' został oficjalnie wprowadzony w Django 3.2, co oznacza, że nie jest dostępny w wcześniejszych wersjach.\\
\\
Przykład z ''EnumField'':

<code python>
from django.db import models

class MyModel(models.Model):
    class Gender(models.TextChoices):
        MALE = 'M', 'Male'
        FEMALE = 'F', 'Female'
        OTHER = 'O', 'Other'

    gender = models.EnumField(Gender, max_length=1)
</code>

Ogólnie rzecz biorąc, stosowanie ''EnumField'' może być bardziej korzystne, gdy chcesz używać dedykowanego typu enumeracyjnego w bazie danych, a także zapewnić bardziej strukturalne i zorganizowane zarządzanie enumeracjami w modelu. Jednak korzystanie z ''choices'' z ''CharField'' lub ''IntegerField'' może być wystarczająco elastyczne i prostsze, jeśli nie wymagasz zaawansowanej obsługi enumeracji.
===== Enumeration types =====

Typy enumeracyjne (''Enumeration types'') w Django, zwłaszcza poprzez ''EnumField'' wprowadzone w Django 3.2 i nowszych, są często stosowane w modelach w przypadkach, gdy pole powinno przyjmować jedną z predefiniowanych, ograniczonych wartości. Poniżej przedstawiam kilka przykładów, gdzie typy enumeracyjne są często używane:

==== Kategorie, Statusy, Stany ====

Enumeracje są przydatne do reprezentowania kategorii, statusów, stanów lub innych ograniczonych zestawów wartości. Na przykład, gdy masz model reprezentujący zamówienie, pole ''status'' może być definiowane jako ''enum'', aby ograniczyć możliwe stany zamówienia.

<code python>
from django.db import models

class Order(models.Model):
    class Status(models.TextChoices):
        PENDING = 'P', 'Pending'
        PROCESSING = 'PR', 'Processing'
        COMPLETED = 'C', 'Completed'

    status = models.CharField(max_length=2, choices=Status.choices)
</code>

==== Typy Kolorów ====

W modelach reprezentujących produkty, pojazdy itp., enumy mogą być używane do reprezentowania predefiniowanych typów kolorów.

<code python>
from django.db import models

class Product(models.Model):
    class Color(models.TextChoices):
        RED = 'R', 'Red'
        GREEN = 'G', 'Green'
        BLUE = 'B', 'Blue'
    color = models.CharField(max_length=1, choices=Color.choices)
</code>
 
==== Płeć ====

Enumeracje mogą być używane do reprezentowania pól, takich jak płeć, gdzie możliwe wartości są ograniczone.

<code python>
from django.db import models

class Person(models.Model):
    class Gender(models.TextChoices):
        MALE = 'M', 'Male'
        FEMALE = 'F', 'Female'
        OTHER = 'O', 'Other'

    gender = models.CharField(max_length=1, choices=Gender.choices)
</code>

==== Priorytety ====

W przypadku modeli z zadaniami, enumy mogą reprezentować priorytety.

<code python>
from django.db import models

class Task(models.Model):
    class Priority(models.TextChoices):
        LOW = 'L', 'Low'
        MEDIUM = 'M', 'Medium'
        HIGH = 'H', 'High'

    priority = models.CharField(max_length=1, choices=Priority.choices)
</code>

==== Typy Dokumentów ====

numy mogą być używane do reprezentowania różnych typów dokumentów, na przykład w modelu reprezentującym przesyłki.

<code python>
from django.db import models

class Shipment(models.Model):
    class DocumentType(models.TextChoices):
        INVOICE = 'I', 'Invoice'
        PACKING_SLIP = 'PS', 'Packing Slip'
        SHIPPING_LABEL = 'SL', 'Shipping Label'

    document_type = models.CharField(max_length=2, choices=DocumentType.choices)
</code>

Wprowadzenie typów enumeracyjnych pomaga w utrzymaniu spójności danych i ułatwia zrozumienie i zarządzanie możliwymi wartościami dla konkretnych pól. Ogranicza także ryzyko pojawienia się błędów związanych z wprowadzaniem niepoprawnych wartości do pól, ponieważ możliwe wartości są z góry określone.
===== db_column =====

Opcja ''db_column'' w polach modeli Django służy do określenia nazwy kolumny w bazie danych, do której dane pole powinno zostać odwzorowane. Domyślnie, Django automatycznie tworzy nazwy kolumn na podstawie nazw pól w modelu, ale opcja ''db_column'' umożliwia dostosowanie nazw kolumn w bazie danych, co może być przydatne w przypadku, gdy nazwy pól w modelu nie są zgodne z preferencjami nazewniczymi bazy danych.\\
\\
Przykład użycia ''db_column'':

<code python>
from django.db import models

class MyModel(models.Model):
    first_name = models.CharField(max_length=50, db_column='custom_first_name')
    last_name = models.CharField(max_length=50, db_column='custom_last_name')
    age = models.IntegerField()
</code>

W tym przykładzie, pola ''first_name'' i ''last_name'' zostały opatrzone opcją ''db_column'', aby określić niestandardowe nazwy kolumn w bazie danych ('''custom_first_name''' i '''custom_last_name''').\\
\\
Użycie ''db_column'' może być przydatne, gdy masz do czynienia z istniejącą bazą danych, która używa określonych nazw kolumn, i chcesz dostosować model Django do tej struktury. Ponadto, może to być również przydatne, jeśli stosujesz pewne konwencje nazewnicze w bazie danych, które różnią się od konwencji nazewniczych Django.\\
\\
Warto jednak używać tej opcji z umiarem i tylko wtedy, gdy jest to naprawdę konieczne, ponieważ automatyczne tworzenie nazw kolumn na podstawie nazw pól w modelu jest jednym z mechanizmów ułatwiających pracę z Django.
===== db_comment =====

Opcja ''db_comment'' w polach modeli Django służy do dodawania komentarza do kolumny w bazie danych. Komentarze w bazie danych są opisami, które mogą zawierać dodatkowe informacje o celu, formatowaniu lub innym kontekście związanym z danym polem. Te komentarze są często używane do dokumentowania struktury bazy danych i mogą być przydatne dla administratorów bazy danych i innych osób pracujących z bazą danych.\\
\\
Przykład użycia ''db_comment'':

<code python>
from django.db import models

class MyModel(models.Model):
    name = models.CharField(max_length=100, db_comment="The name of the item")
    description = models.TextField()
    date_created = models.DateTimeField(db_comment="The date and time when the item was created")
</code>

W tym przykładzie, pola ''name'' i ''date_created'' zostały opatrzone opcją ''db_comment'', aby dodać komentarze do odpowiadających im kolumn w bazie danych.\\
\\
Jest to szczególnie przydatne w przypadku współpracy z zespołem programistycznym, który pracuje nad projektem, a także dla osób administrujących bazę danych. Komentarze mogą dostarczyć dodatkowych informacji na temat znaczenia pól, co ułatwia zrozumienie struktury bazy danych.\\
\\
Warto zauważyć, że dostępność tej opcji może zależeć od używanej bazy danych, ponieważ nie wszystkie systemy zarządzania bazą danych (DBMS) obsługują komentarze na poziomie kolumn. Na przykład, PostgreSQL obsługuje komentarze na poziomie kolumn, podczas gdy niektóre inne DBMS mogą nie mieć tej funkcji.
===== db_index =====

Opcja ''db_index'' w polach modeli Django służy do określania, czy dla danego pola powinien być automatycznie utworzony indeks w bazie danych. Indeksy są strukturami danych, które przyspieszają procesy wyszukiwania i sortowania w bazie danych, poprawiając wydajność zapytań.\\
\\
Przykład użycia ''db_index'':\\

<code python>
from django.db import models

class MyModel(models.Model):
    name = models.CharField(max_length=100, db_index=True)
    description = models.TextField()
    date_created = models.DateTimeField(db_index=True)
</code>

W tym przykładzie, pola ''name'' i ''date_created'' zostały opatrzone opcją ''db_index=True'', co oznacza, że dla tych pól zostaną automatycznie utworzone indeksy w bazie danych.\\
\\
Warto używać indeksów dla pól, które są często używane w zapytaniach filtrujących, sortujących lub grupujących dane, ponieważ indeksy mogą znacznie przyspieszyć te operacje. Jednak zbyt duża liczba indeksów może wpłynąć na wydajność operacji zapisu (np. wstawianie, aktualizacja, usuwanie danych), dlatego warto zbalansować korzyści i koszty związane z indeksowaniem.\\
\\
Django automatycznie tworzy indeksy dla kluczy głównych (''primary_key'') i pól, które są zdefiniowane jako klucze obce (''ForeignKey''). Opcja ''db_index'' daje większą kontrolę nad tym, które dodatkowe pola powinny być indeksowane.\\
\\
Podsumowując, ''db_index'' jest używane do decydowania, czy dla danego pola powinien być automatycznie utworzony indeks w bazie danych w celu poprawy wydajności operacji wyszukiwania i sortowania.
===== db_tablespace =====

Opcja ''db_tablespace'' w polach modeli Django pozwala określić, w którym przestrzeni tabelowej (tablespace) w bazie danych mają być przechowywane dane dla danego pola. Przestrzenie tabelowe są mechanizmem, który umożliwia organizację danych w różnych obszarach dyskowych bazy danych, co może być przydatne w kontekście optymalizacji przechowywania i dostępu do danych.\\
\\
Przykład użycia ''db_tablespace'':\\

<code python>
from django.db import models

class MyModel(models.Model):
    name = models.CharField(max_length=100, db_tablespace='my_custom_tablespace')
    description = models.TextField()
</code>

W tym przykładzie pole ''name'' modelu ''MyModel'' zostało opatrzone opcją ''db_tablespace'', aby wskazać, że dane dla tego pola powinny być przechowywane w przestrzeni tabelowej o nazwie '''my_custom_tablespace'''.\\
\\
W praktyce, dostępność i konfiguracja przestrzeni tabelowej może zależeć od konkretnego systemu zarządzania bazą danych (DBMS), który jest używany (np. PostgreSQL, MySQL, Oracle). Nie wszystkie systemy baz danych obsługują tę opcję, a nawet jeśli obsługują, konfiguracja może różnić się między nimi.\\
\\
Przy wyborze i konfiguracji przestrzeni tabelowej, należy kierować się specyficznymi zaleceniami i dokumentacją dostarczoną przez dostawcę bazy danych, którą używasz. W większości przypadków, szczegóły dotyczące przestrzeni tabelowej są bardziej związane z administracją bazą danych niż z modelem Django, i zazwyczaj są konfigurowane na poziomie samej bazy danych.
===== default =====

Opcja ''default'' w polach modeli Django umożliwia określenie wartości domyślnej dla danego pola, która zostanie ustawiona, gdy nowy rekord zostanie utworzony, a wartość dla tego pola nie zostanie podana.\\
\\
Przykład użycia ''default'':

<code python>
from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)
    publication_year = models.IntegerField(default=2022)
    rating = models.FloatField(default=0.0)
</code>

W tym przykładzie, dla modelu ''Book'', pola ''publication_year'' i ''rating'' zostały opatrzone opcją ''default''. Oznacza to, że jeśli przy tworzeniu nowego rekordu nie zostanie podana wartość dla tych pól, zostanie użyta wartość domyślna.\\
\\
Przykład użycia w kodzie:\\

<code python>
# Utworzenie nowego rekordu
book = Book.objects.create(title='Example Book', author='John Doe')

# Wartości domyślne są automatycznie ustawione
print(book.publication_year)  # Wyświetli: 2022
print(book.rating)  # Wyświetli: 0.0
</code>

Opcja ''default'' jest szczególnie przydatna, gdy chcesz zapewnić sensowną wartość domyślną dla pewnych pól, ale jednocześnie chcesz dać użytkownikowi możliwość nadpisania tej wartości, jeśli to konieczne. Działa to zarówno w przypadku tworzenia nowych rekordów, jak i w przypadku aktualizacji rekordów, które nie mają wartości dla tego pola.
===== editable =====

Opcja ''editable'' w polach modeli Django określa, czy dane pole powinno być dostępne do edycji w interfejsie administracyjnym oraz w formularzach modelu. Domyślnie wszystkie pola są uznawane za edytowalne (''editable=True''), co oznacza, że można je edytować zarówno w interfejsie administracyjnym, jak i w formularzach.\\
\\
Przykład użycia ''editable'':

<code python>
from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField()
    price = models.DecimalField(max_digits=10, decimal_places=2, editable=False)
</code>

W tym przykładzie pole ''price'' zostało ustawione na ''editable=False'', co oznacza, że nie będzie dostępne do edycji w interfejsie administracyjnym ani w formularzach. Można to zastosować do pól, które powinny być automatycznie generowane lub obliczane, takich jak cena, której nie chcesz, aby użytkownicy zmieniali ręcznie.\\
\\
Gdy ''editable'' jest ustawione na ''False'', pole nie jest renderowane jako formularz edycji w interfejsie administracyjnym i nie jest uwzględniane w formularzach modelu. Jednak pole to nadal będzie dostępne do odczytu i wykorzystywane w zapytaniach do bazy danych.
===== error_messages =====

Opcja ''error_messages'' w polach modeli Django umożliwia dostosowanie komunikatów błędów, które są generowane w przypadku problemów związanych z danym polem. Dzięki tej opcji możesz zdefiniować niestandardowe komunikaty błędów dla różnych sytuacji, takich jak nieprawidłowy format, zbyt krótka wartość, itp.\\
\\
Przykład użycia ''error_messages'':

<code python>
from django.db import models

class Person(models.Model):
    username = models.CharField(
        max_length=50,
        error_messages={
            'unique': 'This username is already in use.',
            'max_length': 'Please enter a shorter username.',
            'blank': 'Username cannot be blank.',
        }
    )
    email = models.EmailField(
        error_messages={
            'unique': 'This email address is already registered.',
            'invalid': 'Please enter a valid email address.',
        }
    )
    age = models.IntegerField(
        error_messages={
            'invalid': 'Please enter a valid integer for age.',
        }
    )
</code>

W tym przykładzie, dla modelu ''Person'', pola ''username'', ''email'', i ''age'' zostały opatrzone opcją ''error_messages''. Dla każdego pola zdefiniowano niestandardowe komunikaty błędów dla różnych sytuacji. Na przykład, dla pola ''username'' zdefiniowano komunikaty dla przypadku, gdy wartość jest nieunikalna ('''unique'''), przekracza maksymalną długość ('''max_length'''), lub jest pusta ('''blank''').

Dzięki tej opcji możesz dostosować komunikaty błędów do potrzeb twojej aplikacji lub interfejsu użytkownika, co może poprawić czytelność i zrozumienie komunikatów błędów przez użytkowników.

===== help_text =====

Opcja ''help_text'' w polach modeli Django jest używana do dostarczania krótkiego opisu lub wskazówek dotyczących tego, jak należy wypełnić dane w polu. Jest to pomocne w interfejsie administracyjnym, formularzach oraz wszędzie tam, gdzie dane są wprowadzane lub edytowane. Opcja ta umożliwia deweloperom dostarczenie użytkownikom jasnych informacji na temat oczekiwanych wartości lub formatu dla danego pola.\\
\\
Przykład użycia ''help_text'':

<code python>
from django.db import models

class Person(models.Model):
    first_name = models.CharField(max_length=50, help_text="Enter your first name.")
    last_name = models.CharField(max_length=50, help_text="Enter your last name.")
    age = models.IntegerField(help_text="Enter your age.")

    def __str__(self):
        return f"{self.first_name} {self.last_name}"
</code>

W tym przykładzie, dla modelu ''Person'', pola ''first_name'', ''last_name'' i ''age'' zostały opatrzone opcją ''help_text''. Gdy te pola są używane w interfejsie administracyjnym Django lub w formularzach, użytkownikowi zostaną wyświetlone krótkie wskazówki, które pomogą mu zrozumieć, co powinien wprowadzić w dane pola.\\
\\
Opcja ''help_text'' jest przydatna, ponieważ może poprawić przejrzystość interfejsu użytkownika, zwłaszcza gdy formularze są używane do wprowadzania danych. Dzięki temu użytkownicy mają jasne wskazówki dotyczące oczekiwanych wartości lub formatu, co może zminimalizować błędy wprowadzania danych.
===== primary_key =====

Opcja ''primary_key'' w polach modeli Django jest używana do określenia, które pole w modelu będzie pełnić rolę klucza głównego (primary key) dla tabeli w bazie danych. Klucz główny to unikalny identyfikator, który jednoznacznie identyfikuje każdy rekord w tabeli.\\
\\
Przykład użycia ''primary_key'':\\

<code python>
from django.db import models

class Person(models.Model):
    person_id = models.AutoField(primary_key=True)
    name = models.CharField(max_length=50)
    age = models.IntegerField()

    def __str__(self):
        return self.name
</code>

W tym przykładzie ''person_id'' zostało określone jako klucz główny poprzez ''primary_key=True''. Domyślnie Django automatycznie dodaje klucz główny o nazwie ''id'' (typu ''AutoField''), ale możesz go nadpisać, jak pokazano w przykładzie.\\
\\
Możesz również używać innych pól jako klucza głównego, na przykład:\\

<code python>
class Book(models.Model):
    isbn = models.CharField(primary_key=True, max_length=13)
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)
</code>

W tym przypadku ''isbn'' zostało określone jako klucz główny.\\
\\
Klucz główny jest istotny w relacyjnych bazach danych, ponieważ umożliwia jednoznaczne identyfikowanie każdego rekordu. W Django, jeśli nie zdefiniujesz własnego klucza głównego, Django automatycznie dodaje pole ''id'' jako klucz główny dla każdego modelu. Jednak opcja ''primary_key'' daje kontrolę nad tym, które pole pełni rolę klucza głównego.
===== unique =====

Opcja ''unique'' w polach modeli Django jest używana do narzucenia warunku unikalności dla wartości tego pola w kontekście wszystkich rekordów w bazie danych. Oznacza to, że każda wartość w tym polu musi być unikalna w obrębie całej tabeli.\\
\\
Przykład użycia ''unique'':\\

<code python>
from django.db import models

class Person(models.Model):
    username = models.CharField(max_length=50, unique=True)
    email = models.EmailField(unique=True)
    employee_id = models.CharField(max_length=20, unique=True)

    def __str__(self):
        return self.username
</code>

W powyższym przykładzie, dla modelu ''Person'', trzy pola (''username'', ''email'', ''employee_id'') zostały skonfigurowane z opcją ''unique=True''. Oznacza to, że każda wartość w tych polach musi być unikalna w ramach całej tabeli.\\
\\
Przykład:\\
\\
- Nie można utworzyć dwóch rekordów w tabeli ''Person'' z takim samym ''username''.\\
- Nie można utworzyć dwóch rekordów w tabeli ''Person'' z takim samym ''email''.\\
- Nie można utworzyć dwóch rekordów w tabeli ''Person'' z takim samym ''employee_id''.\\
\\
Ta opcja jest przydatna, gdy chcesz mieć pewność, że dane w określonym polu są unikalne w kontekście całej tabeli. Jest to często stosowane dla pól, które powinny zawierać unikalne identyfikatory, takie jak nazwa użytkownika, adres e-mail, numer identyfikacyjny pracownika, itp.\\
\\
W jednym modelu możesz używać opcji ''unique'' dla kilku pól, ale nie możesz użyć tego samego ''unique'' dla różnych kombinacji pól. Każde ''unique'' musi mieć unikalną kombinację pól. Oto kilka przypadków:

==== Unikalność pojedynczego pola ====

Każde z poniższych pól będzie musiało mieć unikalne wartości w kontekście całej tabeli.

<code python>
class Person(models.Model):
    username = models.CharField(max_length=50, unique=True)
    email = models.EmailField(unique=True)
    employee_id = models.CharField(max_length=20, unique=True)
</code>

==== Unikalność kombinacji pól za pomocą unique_together ====

Możesz użyć ''unique_together'', aby narzucić warunek unikalności dla konkretnej kombinacji pól.

<code python>
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)
    publication_year = models.IntegerField()

    class Meta:
        unique_together = ['title', 'author']
</code>

==== Unikalność różnych kombinacji pól ====

Każda z poniższych kombinacji musi być unikalna.

<code python>
class Product(models.Model):
    serial_number = models.CharField(max_length=20, unique=True)
    manufacturing_date = models.DateField()
    batch_number = models.CharField(max_length=10)

    class Meta:
        unique_together = ['serial_number', 'manufacturing_date']
</code>

W skrócie, możesz użyć opcji ''unique'' dla wielu pól w jednym modelu, ale musisz upewnić się, że każda kombinacja pól jest jednoznacznie unikalna. W przypadku bardziej złożonych warunków unikalności, możesz również korzystać z ''unique_together''.
===== unique_for_date =====

Pole ''unique_for_date'' w modelach Django jest używane do narzucenia warunku unikalności dla wartości pola w ramach jednego dnia kalendarzowego. Oznacza to, że w obrębie jednego dnia wartości tego pola muszą być unikalne w kontekście pozostałych rekordów w bazie danych.\\
\\
Przykład użycia ''unique_for_date'':\\

<code python>
from django.db import models

class Event(models.Model):
    event_name = models.CharField(max_length=100)
    event_date = models.DateField()
    location = models.CharField(max_length=100)
    slug = models.SlugField(unique_for_date='event_date')

    def __str__(self):
        return self.event_name
</code>

W powyższym przykładzie, dla modelu ''Event'', pole ''slug'' zostało skonfigurowane z opcją ''unique_for_date='event_date'''. Oznacza to, że wartości pola ''slug'' muszą być unikalne w ramach jednego dnia kalendarzowego w kontekście wartości pola ''event_date''.\\
\\
Przykład:\\
- Jeśli istnieje wydarzenie o ''event_date='2023-01-15''' z ''slug='example''', to w tym samym dniu nie może istnieć inne wydarzenie z ''slug='example'''.\\
- Jednak w dniu 2023-01-16 można już utworzyć inne wydarzenie z ''slug='example'''.\\
\\
Ta opcja jest przydatna, gdy chcesz upewnić się, że pewne pola są unikalne w ramach jednego dnia kalendarzowego, co może być istotne w przypadku modeli, które reprezentują wydarzenia, daty, czy inne informacje związane z kalendarzem.
===== unique_for_month =====

Opcja ''unique_for_month'' w polach modeli Django jest używana do narzucenia warunku unikalności dla wartości pola w ramach jednego miesiąca kalendarzowego. Oznacza to, że w obrębie jednego miesiąca wartości tego pola muszą być unikalne w kontekście pozostałych rekordów w bazie danych.\\
\\
Przykład użycia ''unique_for_month'':\\

<code python>
from django.db import models

class Event(models.Model):
    event_name = models.CharField(max_length=100)
    event_date = models.DateField()
    location = models.CharField(max_length=100)
    slug = models.SlugField(unique_for_month='event_date')

    def __str__(self):
        return self.event_name
</code>

W powyższym przykładzie, dla modelu ''Event'', pole ''slug'' zostało skonfigurowane z opcją ''unique_for_month='event_date'''. Oznacza to, że wartości pola ''slug'' muszą być unikalne w ramach jednego miesiąca kalendarzowego w kontekście wartości pola ''event_date''.\\
\\
Przykład:\\
- Jeśli istnieje wydarzenie o ''event_date='2023-01-15''' z ''slug='example''', to w tym samym miesiącu nie może istnieć inne wydarzenie z ''slug='example'''.\\
- Jednak w lutym 2023 roku można już utworzyć inne wydarzenie z ''slug='example'''.\\
\\
Ta opcja jest przydatna, gdy chcesz upewnić się, że pewne pola są unikalne w ramach jednego miesiąca kalendarzowego, co może być istotne w przypadku modeli, które reprezentują wydarzenia, daty, czy inne informacje związane z kalendarzem.
===== unique_for_year =====

Opcja ''unique_for_year'' w polach modeli Django jest używana do narzucenia warunku unikalności dla wartości pola w ramach jednego roku kalendarzowego. Oznacza to, że w obrębie jednego roku wartości tego pola muszą być unikalne w kontekście pozostałych rekordów w bazie danych.\\
\\
Przykład użycia ''unique_for_year'':

<code python>
from django.db import models

class Event(models.Model):
    event_name = models.CharField(max_length=100)
    event_date = models.DateField()
    location = models.CharField(max_length=100)
    slug = models.SlugField(unique_for_year='event_date')

    def __str__(self):
        return self.event_name
</code>

W powyższym przykładzie, dla modelu ''Event'', pole ''slug'' zostało skonfigurowane z opcją ''unique_for_year='event_date'''. Oznacza to, że wartości pola ''slug'' muszą być unikalne w ramach jednego roku kalendarzowego w kontekście wartości pola ''event_date''.\\
\\
Przykład:\\
- Jeśli istnieje wydarzenie o ''event_date='2023-01-15''' z ''slug='example''', to w tym samym roku nie może istnieć inne wydarzenie z ''slug='example'''.\\
- Jednak w roku kalendarzowym 2024 można już utworzyć inne wydarzenie z ''slug='example'''.\\
\\
Ta opcja jest przydatna, gdy chcesz upewnić się, że pewne pola są unikalne w ramach jednego roku kalendarzowego, co może być istotne w przypadku modeli, które reprezentują wydarzenia, daty, czy inne informacje związane z kalendarzem.
===== verbose_name =====

Opcja ''verbose_name'' w polach modeli Django służy do dostarczenia czytelnej, ludzkiej nazwy dla pola, która może być używana w interfejsie administracyjnym Django, formularzach, a także w innych sytuacjach, gdzie wymagane jest przedstawienie pola w bardziej zrozumiały sposób.

Przykład użycia ''verbose_name'':

<code python>
from django.db import models

class MyModel(models.Model):
    first_name = models.CharField(max_length=50, verbose_name='First Name')
    last_name = models.CharField(max_length=50, verbose_name='Last Name')
    email = models.EmailField(verbose_name='Email Address')
    date_of_birth = models.DateField(verbose_name='Date of Birth')
</code>

W powyższym przykładzie, dla modelu ''MyModel'', każde pole zostało opatrzone opcją ''verbose_name''. Dzięki temu, gdy korzystasz z interfejsu administracyjnego Django, te nazwy będą wyświetlane zamiast domyślnych nazw generowanych automatycznie na podstawie nazw pól.\\
\\
Opcja ''verbose_name'' ma na celu uczynienie kodu bardziej czytelnym i ułatwienie zrozumienia struktury modelu zarówno dla deweloperów, jak i dla osób pracujących z interfejsem administracyjnym Django.\\
\\
Opcja ''verbose_name'' nie działa tylko w panelu administracyjnym. Chociaż jest szeroko stosowana w interfejsie administracyjnym Django do tworzenia bardziej przyjaznych użytkownikowi etykiet dla pól modeli, jej wpływ sięga poza ten obszar.\\
\\
Oto kilka miejsc, gdzie ''verbose_name'' może mieć wpływ:

==== Panel Administracyjny Django ====

W panelu administracyjnym, ''verbose_name'' jest używane jako etykieta dla pól modelu. Dzięki temu, zamiast korzystać z automatycznie generowanych etykiet na podstawie nazw pól, możesz dostarczyć bardziej czytelne i zrozumiałe nazwy.

==== Formularze Django ====

Przy tworzeniu formularzy Django na podstawie modeli, etykiety pól będą bazować na wartościach ''verbose_name''. Ułatwia to tworzenie formularzy z zrozumiałymi etykietami.

==== API i Serializatory ====

Jeśli używasz Django REST Framework do tworzenia API, ''verbose_name'' może być również używane jako etykieta dla pól w ramach serializatorów. Pomaga to w tworzeniu czytelnych i zrozumiałych struktur danych w API.

==== Szablony Django ====

W szablonach Django, wartość ''verbose_name'' może być używana do dostarczania przyjaznych użytkownikowi etykiet dla pól, co przyczynia się do czytelności i zrozumienia strony internetowej.\\

Podsumowując, chociaż ''verbose_name'' jest szczególnie przydatne w kontekście interfejsu administracyjnego, wprowadza również korzyści w innych obszarach, gdzie używane są informacje na temat struktury modelu.
===== validators =====

Poniżej znajdziesz przykłady wbudowanych opcji i klas walidatorów w Django, które można używać w opcji ''validators'':

==== Opcje dla pól liczbowych ====

''MinValueValidator'': Sprawdza, czy wartość pola jest większa niż lub równa określonemu minimalnemu limitowi.

<code python>
from django.core.validators import MinValueValidator

class MyModel(models.Model):
   number_field = models.IntegerField(validators=[MinValueValidator(limit_value=0)])
</code>

''MaxValueValidator'': Sprawdza, czy wartość pola jest mniejsza niż lub równa określonemu maksymalnemu limitowi.

<code python>
from django.core.validators import MaxValueValidator

class MyModel(models.Model):
    number_field = models.IntegerField(validators=[MaxValueValidator(limit_value=100)])
</code>

==== Opcje dla pól tekstowych ====

''MinLengthValidator'': Sprawdza, czy długość wartości pola jest większa niż lub równa określonemu minimalnemu limitowi.

<code python>
from django.core.validators import MinLengthValidator

class MyModel(models.Model):
    text_field = models.CharField(validators=[MinLengthValidator(limit_value=5)])
</code>

''MaxLengthValidator'': Sprawdza, czy długość wartości pola jest mniejsza niż lub równa określonemu maksymalnemu limitowi.

<code python>
from django.core.validators import MaxLengthValidator

class MyModel(models.Model):
    text_field = models.CharField(validators=[MaxLengthValidator(limit_value=100)])
</code>

''RegexValidator'': Pozwala na zdefiniowanie niestandardowego wyrażenia regularnego do walidacji pola.

<code python>
from django.core.validators import RegexValidator

class MyModel(models.Model):
    custom_field = models.CharField(validators=[RegexValidator(regex=r'^[0-9]*$', message='Only digits are allowed.')])
</code>

==== Opcje dla pól plików ====

''FileExtensionValidator'': Sprawdza, czy nazwa pliku ma określone rozszerzenie.

<code python>
from django.core.validators import FileExtensionValidator

class MyModel(models.Model):
    file = models.FileField(validators=[FileExtensionValidator(allowed_extensions=['pdf', 'doc'])])
</code>

==== Opcje dla pól URL ====

''URLValidator'': Sprawdza, czy wartość pola jest poprawnym adresem URL.

<code python>
from django.core.validators import URLValidator

class MyModel(models.Model):
    website = models.URLField(validators=[URLValidator()])
</code>

==== Opcje dla pól e-mail ====

''EmailValidator'': Sprawdza, czy wartość pola jest poprawnym adresem e-mail.

<code python>
from django.core.validators import EmailValidator

class MyModel(models.Model):
    email = models.EmailField(validators=[EmailValidator()])
</code>

Te przykłady pokazują różne opcje walidatorów dostępnych w Django. Możesz łączyć różne walidatory, dodając je do listy przekazywanej jako argument ''validators'' w definicji pola modelu.\\
\\
Warto sprawdzić [[https://docs.djangoproject.com/en/3.2/ref/validators/|oficjalną dokumentację Django dotyczącą walidatorów]] w celu uzyskania pełnej listy dostępnych opcji i klas walidatorów oraz dodatkowych informacji na ich temat. Jeśli potrzebujesz bardziej zaawansowanych walidacji, możesz również tworzyć własne funkcje walidujące, takie jak ''validate_positive''.\\
\\
Ponadto:\\
\\
''DecimalValidator'' to klasa walidatora w Django, która sprawdza, czy wartość pola numerycznego, takiego jak ''DecimalField'', spełnia określone warunki dotyczące liczby całkowitej, maksymalnej liczby cyfr, maksymalnej liczby cyfr po przecinku, minimalnej liczby cyfr po przecinku itp.\\
\\
Poniżej znajdziesz przykład użycia ''DecimalValidator'':\\

<code python>
from django.core.validators import DecimalValidator
from django.db import models

class Product(models.Model):
    price = models.DecimalField(
        max_digits=10,
        decimal_places=2,
        validators=[
            DecimalValidator(
                max_digits=10,
                decimal_places=2,
                message='Price must have at most 10 digits in total, with 2 digits after the decimal point.',
            ),
            DecimalValidator(
                max_digits=None,
                decimal_places=0,
                message='Price must be an integer.',
            ),
            DecimalValidator(
                max_digits=None,
                decimal_places=2,
                min_digits=1,
                message='Price must have at least 1 digit before the decimal point.',
            ),
        ]
    )
</code>

W tym przykładzie, dla modelu ''Product'', pole ''price'' jest typu ''DecimalField'' z maksymalnie 10 cyfr, z których 2 mogą znajdować się po przecinku. Trzy różne instancje ''DecimalValidator'' zostały użyte jako walidatory dla tego pola, z różnymi warunkami:

  - NumeracjaPierwszy walidator sprawdza, czy cena ma maksymalnie 10 cyfr, z których 2 mogą znajdować się po przecinku.
  - Drugi walidator sprawdza, czy cena jest liczbą całkowitą (nie ma cyfr po przecinku).
  - Trzeci walidator sprawdza, czy cena ma przynajmniej 1 cyfrę przed przecinkiem, z maksymalnie 2 cyframi po przecinku.\\