Framework de comentários do Django

O Django inclui um simples, e ainda customizável framework de comentários. O framework embutido de comentários pode ser usado para atachar comentário a qualquer model, então você pode usá-lo para comentar entradas de blog, photos, capitulos de livros, ou algo mais.

Note

Se você costumava usar o framework antigo (não documentado) de comentários do Django, precisará atualizá-lo. Veja o guia de atualização para instruções.

Guia rápido de início

Para começar a usar a aplicação comments, siga estes passos:

  1. Instale o framework de comentários adicionando 'django.contrib.comments' ao INSTALLED_APPS.

  2. Execute manage.py syncdb, e então o Django criará as tabelas do comments.

  3. Adicione as URLs da aplicação de comentário ao urls.py do seu projeto:

    urlpatterns = patterns('',
        ...
        (r'^comments/', include('django.contrib.comments.urls')),
        ...
    )
    
  4. Use as tags de template do comments abaixo para atachar comentários em seus templates.

Você pode também querer examinar o Configurações de Comentários.

Tags de template do comments

Você irá primeiramente interagir com o sistema de comentários através de uma série de tags de templates que deixam você atachar comentários e gerar formulários para seus usuários para postá-los.

Como toda biblioteca de tags de template customizada, você precisará carregá-as antes de você usá-las:

{% load comments %}

Uma vez carregadas você pode usar as tags de templates abaixo.

Especificando para qual objeto o comentário será atachado

Os comentário do Django são todos "atachados" a algum objeto pai. Este pode ser qualquer instância de um model do Django. Cada uma das tags abaixo lhe dá diferentes formas de especificar a quais objetos serão atachados:

  1. Refere-se ao objeto diretamente -- o método mais comum. Na maioria das vezes, vocÊ terá algum objeto no contexto do template que você deseja atachar os comentários; você pode simplesmente usar este objeto.

    Por exemplo, numa página de entrada de blog que tenha uma variável chamada entry, você poderia usar o seguinte, para carregar o número de comentário:

    {% get_comment_count for entry as comment_count %}.
    
  2. Refere-se ao objeto por content-type e id do objeto. Você poderia usar este método se você, por alguma razão, na verdade não tem o acesso direto ao objeto.

    No exemplo seguinte, se você souber que ID do objeto é 14 mas não tem acesso ao objeto real, você poderia fazer algo tipo:

    {% get_comment_count for blog.entry 14 as comment_count %}
    

    Acima, blog.entry é um label de aplicação e nome de model (em mínusculo) da classe model.

Mostrando comentários

Para obter uma lista de comentários para algum objeto, use get_comment_list:

{% get_comment_list for [object] as [varname] %}

Por exemplo:

{% get_comment_list for event as comment_list %}
{% for comment in comment_list %}
    ...
{% endfor %}

Isto retorna uma lista de objetos Comment; veja a documentação do model comment para detalhes.

Contando comentários

Para contar comentário atachados em um objeto, use get_comment_count:

{% get_comment_count for [object] as [varname]  %}

Por exemplo:

{% get_comment_count for event as comment_count %}

<p>This event has {{ comment_count }} comments.</p>

Mostrando o formulário de comentários

Para mostrar o formulário que os usuários usarão para postar um comentário, você pode usar render_comment_form ou get_comment_form.

Rápidamente renderizando o formulário de comentário

A forma mais fácil de mostrar um formulário de comentário é usando o render_comment_form:

{% render_comment_form for [object] %}

Por exemplo:

{% render_comment_form for event %}

Isto irá renderizar comentários usando um template chamado comments/form.html, uma versão padrão que é incluída no Django.

Renderizando um formulário customizado de comentário

Se você quiser mais controle sobre a aparência do formulário de comentário, você usa o get_comment_form para pegar um objeto form que você pode usar num template:

{% get_comment_form for [object] as [varname] %}

Um formulário completo pode ficar tipo:

{% get_comment_form for event as form %}
<form action="{% comment_form_target %}" method="post">
  {{ form }}
  <tr>
    <td></td>
    <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
  </tr>
</form>

Esteja certo de ler as notas sobre o formulário de comentário, abaixo, para alguma consideração especial que você poderá precisar fazer se estiver utilizando está abordagem.

Pegando o alvo do formulário de comentário

Você pode ter notado que o exemplo acima usa outra tag de template -- comment_form_target -- para na verdade obter o atributo action do formulário. Este sermpre retornará a URL correta para onde o comentário deverá ser postado;

<form action="{% comment_form_target %}" method="POST">

Redirecionando depois de uma postagem de comentário

Para especificar a URL que você quer redirecionar depois que um comentário foi postado, você pode incluir um campo invisível no formulário chamado next. Por exemplo:

<input type="hidden" name="next" value="{% url my_comment_was_posted %}" />

Notas sobre o formulário de comentário

O formulário usado pelo sistema de comentário tem uns poucos atributos anti-spam importantes, que você deve conhecer:

  • Ele contém um número de campos invisíveis que contém timestamps, informações sobre o objeto ao qual o comentário deve estar atachado, e um "hash de segurança" usado para validar estas informações. Se alguém adultera estes dados -- alguns spammers de comentários tentarão -- a submissão falhará.

    Se você estiver renderizando um formulário de comentário customizado, você precisará garantir a passagem destes valores sem mudanças.

  • O timestamp é usado para assegurar que "ataques de resposta" não durem muito tempo. Usuário que esperam muito entre a requisição do formulário e a postagem do comentário terão suas submissões recusadas.

  • O formulário de comentário inclui um campo "honeypot" (pote de mel). Isto é uma armadilha: se algum dado é colocado nesse campo, o comentário será considerado spam (spammers frequêntemente preenchem todos os campos automaticamente, na tentativa de fazer submissões válidas).

    O formulário padrão esconde este campo utilizando um CSS e coloca nele um label adicional com um aviso de campo; Se você usar o formulário de comentário com um template customizado, deve assegurar-se de fazer o mesmo.