Tutorial: Criar um aplicativo Django com modos de exibição e modelos de página no Visual Studio

Este artigo apresenta a Etapa 2 da série de tutoriais Trabalhar com a estrutura da Web Django no Visual Studio.

O Visual Studio permite que você crie aplicativos Django a partir de modelos de projeto que fornecem um ponto de partida mais extenso para seus projetos. Etapa 1 da série de tutoriais descreve como criar os arquivos de configuração no nível do site para um projeto Web Django para suportar um ou mais aplicativos Web Django. Na Etapa 2, você adiciona conteúdo ao seu projeto Web Django para criar seu primeiro aplicativo Web Django com uma única página com várias visualizações renderizadas.

Na etapa 2 do tutorial, você aprenderá a:

• Criar um aplicativo Django com uma única página
• Execute o aplicativo a partir do projeto Django
• Gerar uma visualização usando HTML
• Renderizar uma exibição usando um modelo de página do Django

Pré-requisitos

• Uma solução Visual Studio e um projeto Django criados em Etapa 1: Criar solução Visual Studio e projeto Django.

• Consulte a seção Pré-requisitos na Etapa 1 desta série de tutoriais para obter detalhes sobre versões de modelo Django, projetos do Visual Studio versus projetos Django e desenvolvimento Python no Mac OS.

Criar aplicativo Django com estrutura padrão

Um aplicativo Django é um pacote Python separado que contém um conjunto de arquivos relacionados para uma finalidade específica. Um projeto Django pode conter muitos aplicativos, que ajudam um host a servir muitos pontos de entrada separados (ou rotas ) de um único nome de domínio. Por exemplo, um projeto Django para um domínio como contoso.com pode conter um aplicativo para a rota www.contoso.com, um segundo aplicativo para a rota support.contoso.com e um terceiro aplicativo para a rota docs.contoso.com. Nesse cenário, o projeto Django manipula o roteamento de URL no nível do site e as configurações nos arquivos urls.py e settings.py. Cada aplicativo tem seu próprio estilo e comportamento distintos por meio de seu roteamento interno, exibições, modelos, arquivos estáticos e interface administrativa.

O desenvolvimento de um aplicativo Django geralmente começa com um conjunto padrão de arquivos. O Visual Studio fornece modelos para inicializar um aplicativo Django com esses arquivos dentro de um projeto Django. Há também um comando de menu integrado que serve o mesmo propósito.

Usar modelo para criar aplicativo

Siga estas etapas para criar o aplicativo a partir de um modelo:

1. No Gerenciador de Soluções , clique com o botão direito do mouse no projeto do Visual Studio (BasicProject) e selecione Adicionar>Novo Item.

   

2. Na caixa de diálogo Adicionar Novo Item, selecione o modelo do aplicativo Django 1.9:

   1. Digite o aplicativo NomeHelloDjangoApp.

   2. Selecione Adicionar.

   

Use o comando de menu integrado para criar um aplicativo

Siga estas etapas para criar o aplicativo usando o comando de menu Django integrado:

1. No Explorador de Soluções , clique com o botão direito do rato no projeto do Visual Studio (BasicProject) e selecione Adicionar aplicação Django>.

   

2. Na caixa de diálogo Adicionar aplicação Django, digite o nome da aplicação HelloDjangoApp:

   

3. Selecione OK.

Explore a pasta do aplicativo Django

Quando você cria o aplicativo HelloDjangoApp, o Visual Studio cria uma pasta com o mesmo nome em seu projeto do Visual Studio:

A pasta contém os seguintes itens:

Número	Descrição
migrações	Uma pasta na qual o Django armazena scripts que atualizam o banco de dados para alinhar com as alterações nos modelos. As ferramentas de migração do Django aplicam as alterações necessárias a qualquer versão anterior do banco de dados para corresponder aos modelos atuais. Ao usar migrações, você mantém o foco em seus modelos e permite que o Django manipule o esquema de banco de dados subjacente. Para os exercícios desta série de tutoriais, a pasta contém um arquivo __init__.py, que indica que a pasta define seu próprio pacote Python. Para obter mais informações, consulte a documentação do Django.
__init__.py	A presença do arquivo init identifica o aplicativo Django como um pacote.
modelos	Uma pasta para modelos de página do Django que contém um único arquivo index.html. O arquivo index.html é colocado na pasta que tem o mesmo nome do aplicativo. Os modelos são blocos de HTML nos quais as exibições podem adicionar informações para renderizar dinamicamente uma página. As "variáveis" do modelo de página, como {{ content }} no arquivo index.html, são espaços reservados para valores dinâmicos, conforme explicado mais adiante neste artigo. Normalmente, os aplicativos Django criam um namespace para seus modelos colocando-os em uma subpasta que corresponde ao nome do aplicativo.
admin.py	O arquivo Python no qual você estende a interface administrativa do aplicativo, que é usado para exibir e editar dados em um banco de dados. Inicialmente, este arquivo contém apenas a instrução from django.contrib import admin. Por padrão, o Django inclui uma interface administrativa padrão por meio de entradas no arquivo settings.py do projeto Django. Para ativar a interface, você pode descomentar as entradas existentes no arquivo urls.py.
apps.py	Um arquivo Python que define uma classe de configuração para o aplicativo. (Veja o exemplo a seguir a esta tabela.)
models.py	Os modelos são objetos de dados, identificados por funções, através dos quais as vistas interagem com a base de dados subjacente da aplicação. O Django fornece a camada de conexão do banco de dados para que os aplicativos não se preocupem com os detalhes dos modelos. O arquivo models.py é um local padrão onde você cria seus modelos. Inicialmente, o arquivo models.py contém apenas a instrução from django.db import models.
tests.py	Um arquivo Python que contém a estrutura básica de testes de unidade.
views.py	As visualizações são semelhantes às páginas da Web, que recebem uma solicitação HTTP e retornam uma resposta HTTP. Normalmente, as visualizações são renderizadas como HTML e os navegadores da Web sabem como exibir, mas uma exibição não precisa necessariamente ser visível (como um formulário intermediário). Uma função Python define a visualização que processa o HTML para o navegador. O arquivo views.py é um local padrão onde você cria suas exibições. Inicialmente, o arquivo views.py contém apenas a instrução from django.shortcuts import render.

Quando você usa o nome "HelloDjangoApp", o conteúdo do arquivo apps.py aparece da seguinte maneira:

from django.apps import AppConfig

class HelloDjangoAppConfig(AppConfig):
    name = 'HelloDjangoApp'

Criar aplicativo no Visual Studio ou a partir da linha de comando

O comando Add>Django app e o comando Add>New Item (combinado com um modelo de aplicativo Django) produzem os mesmos arquivos que o comando Django CLI manage.py startapp <app_name>. O benefício de criar o aplicativo Django no Visual Studio é que a pasta do aplicativo e todos os seus arquivos são integrados automaticamente no projeto. Você pode usar o mesmo comando do Visual Studio para criar qualquer número de aplicativos em seu projeto.

Adicionar visualizações de página específicas do aplicativo

Se você executar seu projeto atual no Visual Studio selecionando Depurar>Iniciar Depuração (F5) ou Servidor Web na barra de ferramentas principal, você verá a página padrão do Django. Os aplicativos Web geralmente têm várias páginas com modos de exibição diferentes. Uma rota exclusiva para o endereço URL do aplicativo identifica cada página no aplicativo.

Siga estas etapas para definir visualizações de página específicas do aplicativo e adicionar o aplicativo ao projeto Django:

1. Na subpasta HelloDjangoApp do seu projeto do Visual Studio, substitua o conteúdo do arquivo views.py com o seguinte código:

   from django.shortcuts import render
   from django.http import HttpResponse
   
   def index(request):
       return HttpResponse("Hello, Django!")
   

   Esse código importa as definições de renderização e HTTP necessárias e define uma exibição chamada index.

2. Na subpasta BasicProject do seu projeto do Visual Studio, modifique o arquivo urls.py para corresponder ao código a seguir. Você pode manter os comentários instrutivos no arquivo atual, como preferir.

   from django.urls import include, re_path
   import HelloDjangoApp.views
   
   # Django processes URL patterns in the order they appear in the array
   urlpatterns = [
       re_path(r'^$', HelloDjangoApp.views.index, name='index'),
       re_path(r'^home$', HelloDjangoApp.views.index, name='home')
   ]
   

Cada padrão de URL descreve as visualizações para as quais o Django roteia URLs específicas relativas ao site (ou seja, a parte da rota que segue o endereço de URL https://www.domain.com/):

• A primeira entrada na definição de urlPatterns que começa com a expressão regular ^$ é o roteamento para a página raiz do site, /.
• A segunda entrada, ^home$, direciona para a página /home da aplicação.

Observe que a definição neste código de exemplo demonstra que você pode ter vários roteamentos para a mesma exibição.

Defina as cadeias de caracteres de rota brutas com o prefixo (r)

O prefixo r numa string de rota em Python significa "literal". Este prefixo instrui Python a não efetuar escape de nenhum caractere dentro da string de rota. As expressões regulares para sequências de rota usam muitos caracteres especiais. O prefixo r em uma cadeia de caracteres de rota é mais fácil de ler do que o caractere de escape \.

Use o acento circunflexo (^) e o cifrão ($) nas rotas

Em expressões regulares que definem padrões de URL, o símbolo de acento circunflexo ^ significa "início de linha" e o cifrão $ significa "fim de linha". Há vários usos para esses caracteres em URLs relativos à raiz do site (a parte que segue o endereço do aplicativo https://www.domain.com/):

• A expressão regular ^$ efetivamente significa "em branco" e corresponde ao URL completo da raiz do site do aplicativo, https://www.domain.com/.
• O padrão ^home$ coincide exatamente com https://www.domain.com/home/, que é a rota do site seguida por /home. (Django não usa o trailing / na correspondência de padrões.)
• Se não usares um cifrão à direita $ numa expressão regular, como para a string de rota ^home, a correspondência de padrões de URL aplicar-se-á a qualquer URL que comece com home tal como home, homework, homestead, home192837, e assim por diante.

Para experimentar diferentes expressões regulares, experimente ferramentas online como regex101.com at pythex.org.

Executar aplicativo do projeto Django

Depois de adicionar conteúdo específico do aplicativo, execute seu aplicativo novamente e verifique as visualizações de rota no navegador:

1. Quando o aplicativo for aberto no navegador, verifique as visualizações de página para as rotas de URL / (raiz do site) e /home. Para ambas as rotas, o aplicativo exibe a mensagem Olá, Django! no navegador.

2. Quando terminar, selecione Ctrl+C na janela do console, seguido de qualquer tecla para parar o aplicativo. Você também pode selecionar Depurar>Parar Depuração.

3. Feche todas as janelas abertas do navegador para o aplicativo.

Confirmar alterações no controle do código-fonte

Depois de atualizar o código do aplicativo Django e testar as atualizações, você pode revisar e confirmar suas alterações no controle do código-fonte:

1. Salve as alterações em seus arquivos de projeto, como com o atalho de teclado Ctrl+S.

2. Na barra de controle do Git, selecionar as alterações não confirmadas (ícone de lápis 11) para abrir a janela Git Changes:

   

3. Na janela Git Changes, insira uma mensagem de confirmação e selecione Confirmar tudo:

   

   Quando a confirmação for concluída, o Visual Studio exibirá a mensagem Confirmar <hash> criado localmente.

4. (Opcional) Envie as alterações confirmadas para o repositório remoto:

   1. Na barra de controles do Git, selecione as confirmações de saída/entrada (setas 1/0).

   2. Selecione Sincronizar (Pull e depois Push) ou Push.

   

   Você também pode acumular vários commits locais antes de enviá-los para o repositório remoto.

Para procedimentos subsequentes nesta série de tutoriais, você pode consultar esta seção para obter as etapas para confirmar alterações no controle do código-fonte.

Usar modelos para renderizar páginas e modos de exibição

A função index no arquivo views.py gera uma resposta HTTP de texto simples para a página do aplicativo Django. A maioria das páginas da Web do mundo real responde com páginas HTML ricas que geralmente incorporam dados dinâmicos. A principal razão pela qual os desenvolvedores definem modos de exibição usando uma função é gerar conteúdo dinamicamente.

O argumento para o método HttpResponse é apenas uma cadeia de caracteres. Você pode criar qualquer HTML dentro de uma cadeia de caracteres usando conteúdo dinâmico. Como é melhor separar a marcação dos dados, é melhor colocar a marcação em um modelo e manter os dados no código.

Ajustar modos de exibição para usar HTML embutido

Converta o processamento de exibição para usar HTML embutido para a página com algum conteúdo dinâmico:

1. Na subpasta HelloDjangoApp do seu projeto do Visual Studio, abra o arquivo views.py.

2. Substitua a função index pelo seguinte código (mantenha as instruções from existentes):

   from datetime import datetime
   
   def index(request):
      now = datetime.now()
   
      html_content = "<html><head><title>Hello, Django</title></head><body>"
      html_content += "<strong>Hello Django!</strong> on " + now.strftime("%A, %d %B, %Y at %X")
      html_content += "</body></html>"
   
      return HttpResponse(html_content)
   

   A função index revisada gera uma resposta HTML usando conteúdo dinâmico que é atualizado sempre que você atualiza a página.

3. Salve suas alterações e execute seu aplicativo novamente. A página agora mostra a data e a hora atuais, juntamente com a mensagem "Olá Django!".

4. Atualize a página algumas vezes para confirmar que a data e a hora são atualizadas. Quando terminar, pare o aplicativo.

Criar modelo HTML para visualizações de página

Gerar HTML em código funciona bem para páginas pequenas. No entanto, à medida que as páginas se tornam mais sofisticadas, você precisa manter as partes HTML estáticas da sua página (juntamente com referências a arquivos CSS e JavaScript) como "modelos de página". Em seguida, você pode inserir o conteúdo dinâmico gerado por código nos modelos de página. Na seção anterior, apenas a data e a hora da chamada de now.strftime são dinâmicas, o que significa que todo o outro conteúdo pode ser colocado em um modelo de página.

Um modelo de página Django é um bloco de HTML que contém vários tokens de substituição chamados "variáveis". Abrir e fechar parênteses encaracolados {{ e }} delinear as variáveis, como {{ content }}. Em seguida, o módulo de modelo do Django substitui as variáveis pelo conteúdo dinâmico que você fornece no código.

Siga estas etapas para converter o processo de renderização de página para usar um modelo HTML:

1. Na subpasta HelloDjangoApp do seu projeto do Visual Studio, abra o arquivo settings.py.

2. Atualize as referências do aplicativo na definição de INSTALLED_APPS para incluir o nome do aplicativo HelloDjangoApp. Adicione o nome do aplicativo como a primeira entrada na lista:

   INSTALLED_APPS = [
       'HelloDjangoApp',
       # Existing entries in the list ...
   ]
   

   Adicionar o aplicativo à lista informa ao projeto Django que há uma pasta chamada HelloDjangoApp que contém um aplicativo.

3. Confirme a configuração do objeto TEMPLATES que define APP_DIRS para True.

   'APP_DIRS': True,
   

   Esta instrução instrui o Django a procurar modelos na pasta modelos para um aplicativo instalado. (Esta declaração deve ser incluída na definição por padrão.)

4. Na subpasta HelloDjangoApp, abra o ficheiro de modelo de página templates/HelloDjangoApp/index.html.

5. Confirme se o arquivo contém apenas uma variável, {{ content }}:

   <html>
     <head>
       <title></title>
     </head>
   
     <body>
       {{ content }}
     </body>
   </html>
   

   A instrução {{ content }} é um espaço reservado ou token de substituição (também chamado de variável de modelo ) para o qual você fornece um valor no código.

6. Na subpasta HelloDjangoApp do seu projeto do Visual Studio, abra o arquivo views.py.

7. Substitua a função index pelo seguinte código que usa a função auxiliar django.shortcuts.render (mantenha as instruções from existentes):

   def index(request):
      now = datetime.now()
   
      return render(
         request,
         "HelloDjangoApp/index.html",  # Relative path from the 'templates' folder to the template file
         {
            'content': "<strong>Hello Django!</strong> on " + now.strftime("%A, %d %B, %Y at %X")
         }
      )
   

   A função auxiliar render fornece uma interface simplificada para trabalhar com modelos de página. Esta função tem três argumentos:

   • O objeto de solicitação.
   • O caminho relativo para o ficheiro de modelo dentro da pasta de modelos do aplicativo. Um arquivo de modelo é nomeado para a exibição que ele suporta, se apropriado.
   • Um dicionário de variáveis a que o modelo se refere. Você pode incluir objetos no dicionário, onde uma variável no modelo pode se referir a {{ object.property }}.

8. Salve as alterações do projeto e execute o aplicativo novamente.

   Observe que a sintaxe HTML embutida (\<strong> ...) dentro do valor content não renderiza como HTML porque o mecanismo de modelagem (Jinja) escapa automaticamente do conteúdo HTML. A fuga automática evita vulnerabilidades acidentais a ataques de injeção.

   Os desenvolvedores frequentemente recolhem entradas de uma página e utilizam-nas como um valor noutra, recorrendo a um marcador de posição de modelo. Escapar também serve como um lembrete de que é melhor manter o HTML fora do código.

   Quando terminar, pare o aplicativo.

Utilize espaços reservados distintos

Você pode usar espaços reservados distintos para cada elemento de dados no HTML. Em seguida, ajuste a função index novamente para fornecer os valores de espaço reservado específicos:

1. Substitua o conteúdo do arquivo de modelo de página templates/HelloDjangoApp/index.html pela seguinte marcação:

   <html>
     <head>
       <title>{{ title }}</title>
     </head>
     <body>
       <strong>{{ message }}</strong>{{ content }}
     </body>
   </html>
   

   Essa marcação HTML adiciona um título de página e mantém toda a formatação no modelo de página.

2. No arquivo HelloDjangoApp/views.py, substitua a função index com o seguinte código:

   def index(request):
       now = datetime.now()
   
       return render(
           request,
           "HelloDjangoApp/index.html",  # Relative path from the 'templates' folder to the template file
           # "index.html", # Use this code for VS 2017 15.7 and earlier
           {
               'title' : "Hello Django",
               'message' : "Hello Django!",
               'content' : " on " + now.strftime("%A, %d %B, %Y at %X")
           }
       )
   

   Este código fornece valores para todas as variáveis no modelo de página.

3. Salve suas alterações e execute seu aplicativo novamente. Desta vez, você deve ver a saída renderizada corretamente:

   

4. Você pode confirmar suas alterações no controle do código-fonte e atualizar seu repositório remoto. Para obter mais informações, consulte Confirmar alterações no controle do código-fonte.

Modelos de página separados

Os modelos geralmente são mantidos em arquivos HTML separados, mas você também pode usar um modelo embutido. Arquivos separados são recomendados para manter uma separação limpa entre marcação e código.

Usar extensão .html para modelos

A extensão .html para arquivos de modelo de página é totalmente opcional. Você sempre pode identificar o caminho relativo exato para o arquivo no primeiro argumento para a função render_template. No entanto, o Visual Studio (e outros editores) normalmente fornece recursos como completamento de código e coloração de sintaxe com arquivos .html, o que compensa o facto de que os modelos de página não são HTML.

Quando você trabalha com um projeto Django, o Visual Studio deteta automaticamente se o arquivo HTML que você está editando é realmente um modelo Django e fornece determinados recursos de preenchimento automático. Se você começar a inserir um comentário de modelo de página Django ({#), o Visual Studio fornecerá automaticamente os #} caracteres de fechamento. Os comandos Seleção de Comentário e Seleção de Cancelamento de Comentário (no menu Editar> Avançado) também usam comentários de modelo em vez de comentários HTML.

Solucionar problemas

Ao executar seu aplicativo, você pode encontrar problemas relacionados ao arquivo de modelo para seu aplicativo. Analise os pontos a seguir e verifique se a configuração do seu projeto Django está correta.

Modelo não encontrado

Se o Django ou o Visual Studio exibir um Modelo não encontrado erro, verifique se seu aplicativo está na lista INSTALLED_APPS. Essa lista está no arquivo settings.py na subpasta do aplicativo do seu projeto do Visual Studio (como HelloDjangoApp). Se a lista não tiver uma entrada para seu aplicativo, o Django não saberá procurar nos modelos do aplicativo pasta.

Estrutura de modelo duplicada

Quando o Django procura um modelo referido na função render, ele usa o primeiro arquivo que corresponde ao caminho relativo. Se você tiver vários aplicativos Django no mesmo projeto com as mesmas estruturas de pastas para modelos, é provável que um aplicativo possa usar involuntariamente um modelo de outro aplicativo. Para evitar esses erros, sempre crie uma subpasta sob os modelos de de um aplicativo pasta que corresponda ao nome do aplicativo para evitar qualquer duplicação.

Próximo passo

Etapa 3: Servir ficheiros estáticos, adicionar páginas e usar herança de templates