# documentação Django 2.0.8

# Django em um relance

Como o Django foi desenvolvido no ambiente movimentado de uma redação, ele foi desenhado para tornar as tarefas comuns do desenvolvimento Web rápidas e fáceis. Aqui está uma visão informal sobre como escrever uma aplicação Web dirigida a banco de dados com Django.

O objetivo deste documento é dar a você as especificações técnicas necessárias para entender como o Django funciona, mas este texto não pretende ser um tutorial ou uma referência – mas possuímos os dois! Quando você estiver pronto para iniciar um projeto, você pode iniciar com o tutorial ou mergulhar direto em uma documentação mais detalhada.

## Projete o seu model

Embora você possa usar o Django sem um banco de dados, ele vem com um mapeador objeto-relacional no qual você descreve o layout da sua base de dados em código Python.

A sintaxe do modelo de dados oferece muitas formas ricas de representar seus models – portanto, ela está resolvendo cerca de dois anos de problemas de esquemas de base de dados. Aqui está um exemplo rápido:

mysite/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

## Instale-o

Em seguida, rode o utilitário de linha de comando do Django para criar as tabelas da base de dados automaticamente:

    $ python manage.py migrate

O comando :djadmin:``migrate` procura por todos os seus modelos disponíveis e cria as tabelas na sua base de dados caso as tabelas ainda não existam, bem como, opcionalmente, fornecendo controle muito mais rico do seu esquema de dados.

## Aproveite a API livre

Com ela você irá ter uma API Python livre e rica para acessar seus dados. A API é criada em tempo de execução, nenhuma geração de código é necessária:

    # 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()

## Uma interface de administração dinâmica: não se trata apenas de andaimes - é toda a casa.

Uma vez que seu modelos estejam definidos, o Django pode automaticamente criar um website profissional e pronto para produção administrative interface – que deixe usuários adicionar, alterar e deletar objetos. Isso é fácil registrando seu modelo no “admin site”.

mysite/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)

mysite/news/admin.py

    from django.contrib import admin

    from . import models

    admin.site.register(models.Article)

A filosofia aqui é que seu site é editado por uma equipe, ou um cliente, ou talvez apenas por você – e você não quer ter que lidar com criação de interfaces backend apenas para gerenciar conteúdo.

Um workflow típico na criação de aplicações Django é criar os models e ter os sites administrativos rodando o mais rápido possível, assim sua equipe (ou cliente) poderá começar a inserir os dados. Em seguida, desenvolve-se a forma com que os dados serão apresentados ao público.

## Projete suas URLs

Um esquema limpo e elegante de URLs é um detalhe importante em uma aplicação Web de alta qualidade. O Django encoraja o desenho de belíssimas URLs e não coloca nenhuma sujeira nelas, como `.php` ou `.asp`.

Para desenhar URLs para uma aplicação, você cria um módulo Python chamado URLconf. Uma tabela de conteúdos para sua aplicação, contendo um mapeamento simples entre padrões de URL e funções Python. URLconfs também servem para desacoplar as URLs do código Python.

Aqui está como um URLconf se aparentaria para o exemplo `Reporter`/`Article` acima:

mysite/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),
    ]

The code above maps URL paths to Python callback functions (“views”). The path strings use parameter tags to “capture” values from the URLs. When a user requests a page, Django runs through each path, in order, and stops at the first one that matches the requested URL. (If none of them matches, Django calls a special-case 404 view.) This is blazingly fast, because the paths are compiled into regular expressions at load time.

Once one of the URL patterns matches, Django calls the given view, which is a Python function. Each view gets passed a request object – which contains request metadata – and the values captured in the pattern.

Por exemplo, se um usuário solicita a URL “/articles/2005/05/39323/”, Django chamaria a função `news.views.article_detail(request, year=2005, month=5, pk=39323)`.

## Escreva suas views

Cada view é responsável por fazer uma entre duas coisas: Retornar um objeto `HttpResponse` contendo o conteúdo para a página requisitada, ou levantar uma exceção como `Http404`. O resto é com você.

Geralmente, uma view recupera dados de acordo com os parâmetros, carrega um template e renderiza o template com os dados recuperados. Aqui está uma view para o `year_archive` do exemplo acima:

mysite/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)

Esse exemplo usa o sistema de template do Django, o qual possui diversos recursos poderosos mas prima por permanecer simples o suficiente para que não-programadores possam usá-lo.

## Projete seus templates

O código acima carrega o template `news / year_archive.html`.

O Django tem um caminho de pesquisa para templates, o qual permite a você minimizar a redundância entre templates. Nas configurações do Django, você especifica uma lista de diretórios para procurar por templates `DIRS`. Se um template não existir no primeiro diretório, ele verifica o segundo e assim por diante.

Vamos dizer que o template `news/article_detail.html` foi encontrado. Aqui está como ele deve se parecer:

mysite/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 %}

Variáveis são cercadas por chaves duplas. `{{ article.headline }}` que significa “retorne o valor do atributo headline do artigo”, mas pontos não são usados apenas para acessar atributos: eles também podem acessar chaves de dicionários, acesar índices e chamar funções.

Note que `{{ article.pub_date|date:"F j, Y" }}` usa um “pipe” no estilo Unix (o caractere “|”). Isso é chamado de filtro de template, e é uma forma de filtrar o valor de uma variável. Nesse caso, o filtro “date” formata um objeto Python datetime para um formato dado (como o encontrado na função date do PHP).

Você pode atrelar tantos filtros quanto você quiser. Você pode escrever filtros personalizados. Você pode escrever tags de template personalizadas, que irão rodar código Python personalizado por baixo dos panos.

Finalmente, o Django usa o conceito de “herança de templates”: É isso que o `{% extends "base.html" %}` faz. Isso significa “primeiro carregue o template chamado ‘base’, o qual define uma série de blocos, e preencha os blocos com os seguintes blocos”. Resumindo, isso permite a você reduzir drasticamente a redundância em seus templates: cada template tem que definir apenas aquilo que é único para aquele template.

Aqui está como o template “base.html”, incluindo o uso de arquivos estáticos, deve se parecer:

mysite/templates/base.html

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

Simplesmente, ele define a aparência do site (com o logotipo do site), e fornece “buracos” para templates filhos preencherem. Isso torna o redesign do site tão fácil quanto modificar um único arquivo – o template base.

Isso também permite a você criar múltiplas versões de um site, com templates base diferentes, enquanto reutiliza templates filhos. Os criadores do Django utilizaram essa técnica para criar versões de sites para celulares totalmente diferentes – simplesmente criando um novo template base.

Note que você não tem que usar o sistema de templates do Django se você preferir outro. Enquanto o sistema de templates do Django é particularmente bem integrado com a camada de modelos do Django, nada força você a usá-lo. Da mesma maneira que, você não tem que usar a API de banco de dados do Django, também. Você pode usar outras camadas de abstração de banco de dados, você pode ler arquivos XML, você pode ler arquivos do disco, ou qualquer coisa que desejar. Cada parte do Django – models, views e templates – é desacoplada da próxima.

## Isto é apenas a superfície

Esta foi apenas uma breve visão geral da funcionalidade do Django. Algumas características mais úteis:

- Um framework para caching que se integra com o memcached e outros backends.
- Um syndication framework que torna a criação de RSS e Atom uma tarefa tão fácil quanto escrever uma classe Python.
- Mais recursos sexy da administração gerada automaticamente – essa introdução mal arranhou a superfície.

Os próximos passos óbvios para você fazer é baixar o Django, ler o tutorial e juntar-se a comunidade. Obrigado pelo seu interesse!