Commit da5d345a350410341566c32889389bae789deef8
1 parent
944b7e71
Exists in
master
and in
5 other branches
Guia do Breadcrumbs [PT-BR] #459
Showing
4 changed files
with
83 additions
and
4 deletions
Show diff stats
README.md
| ... | ... | @@ -122,6 +122,85 @@ curl -H "Authorization: Bearer <your_access_token>" -X POST -d"username=foo&pass |
| 122 | 122 | * log detail ("/logs/id") (id is a parameter) |
| 123 | 123 | |
| 124 | 124 | |
| 125 | +## Breadcrumbs | |
| 126 | +[PT-BR] | |
| 127 | +Os **breadcrumbs** reduzem o número de ações que um usuários precisa tomar para chegar a uma página de nível superior e melhorar o nível de encontrabilidade de seções e páginas. | |
| 128 | + | |
| 129 | +No amadeus estamos utilizando a lib [django-bootstrap-breadcrumbs](http://django-bootstrap-breadcrumbs.readthedocs.io/en/latest/) para oferecer essa facilidade aos nosso usuários. | |
| 130 | + | |
| 131 | +**Como usar:** | |
| 132 | +O pacote já se encontra instalado no projeto. Ele está na lista das dependências que se encontram no arquivo `requirements.txt` que foi instalado anteriormente. Então para usar a lib num template, você só precisa fazer o load da tag: ```{% load django_bootstrap_breadcrumbs %}``` | |
| 133 | + | |
| 134 | +O pacote assume que você tem uma boa organização de urls no seu projeto para que ele possa funcionar como esperado. Ele funciona a base herança de templates, como assim? | |
| 135 | + | |
| 136 | +No arquivo ```core > templates > base.html``` existe um bloco denominado ***breadcrumbs***, que é o bloco que deve ser alterado pelos templates que herdam do ```base.html```. O outro bloco que vem logo a seguir ***render_breadcrumbs*** é o bloco responsável por renderizar todo o HTML que é gerado pelo bloco enterior, e ele só deve ser usado uma única vez. | |
| 137 | +TODOS os arquivos que herdam do template ```base.html``` ou de outro template que herdou dele, deve implementar o bloco ***breadcrumbs***. | |
| 138 | + | |
| 139 | +***Exemplo*** | |
| 140 | +Como a nossa dashboard comoça na app ```app```, é nesse app que foi feito a primeira herança do bloco ***breadcrumbs*** e a partir dalí todos os apps estendem dos templates dessa app. | |
| 141 | +Vamos ilustrar um exemplo de breadcrumbs que vai até a página de criar uma discilina dentro de um curso: | |
| 142 | + | |
| 143 | +```1 - home.html``` | |
| 144 | +O arquivo ```1``` se encontra na app ```app``` e ele faz herança do template ```base.html``` | |
| 145 | + | |
| 146 | +```python | |
| 147 | +1 {% block breadcrumbs %} | |
| 148 | +2 | |
| 149 | +3 {% clear_breadcrumbs %} | |
| 150 | +4 {% breadcrumb 'Home' 'app:index' %} | |
| 151 | +5 | |
| 152 | +6 {% endblock %} | |
| 153 | +7 | |
| 154 | +8 {% block render_breadcrumbs %} | |
| 155 | +9 {% render_breadcrumbs %} | |
| 156 | +10 {% endblock %} | |
| 157 | +``` | |
| 158 | + | |
| 159 | +A linha 3 é responsável por 'limpar' todo o breadcrumbs feito anteriormente, ou seja, se existisse algum breadcrumbs no trmplate herdado por ```home.html```, ele não vai existir a partir desse template. Por isso é recomendado usar essa tag somente no template root do breadcrumbs, egg: na home. | |
| 160 | + | |
| 161 | +A linha 4, é onde a mágica acontece. É o breadcrumb da página em si. | |
| 162 | +O primeiro parâmetro da template tag: o 'Home', é o texto que vai ficar linkado(quando você estiver em uma outra página). Ele pode ser um texto, que tem que vir entres aspas, por exemplo 'Home', ou pode ser uma variavel do template que nesse caso não precisa de aspas. O segundo parâmetro é a url da página em que o template em questão vai ser exibida, ou seja, ele chama a sua própria ulr, como era de se esperar. | |
| 163 | +***OBS:*** Se a url tivesse um parâmetro, ele devia ser passado como um terceiro argumento da template tag. | |
| 164 | +***OBS2:*** A linha 9 só precisa ser chamado uma única vez e deve ser na template home, egg: os templates que não são o root do breadcrumbs não precisam subsvrever o bloco 'render_breadcrumbs' | |
| 165 | + | |
| 166 | +```2 - courses > templates > course > index.html``` | |
| 167 | +O arquivo ```2``` é o index da app ```courses``` e ele herda o template ```1```. | |
| 168 | +```python | |
| 169 | +1 {% block breadcrumbs %} | |
| 170 | +2 | |
| 171 | +3 {{ block.super }} | |
| 172 | +4 {% breadcrumb 'Courses' 'course:manage' %} | |
| 173 | +5 | |
| 174 | +6 {% endblock %} | |
| 175 | +``` | |
| 176 | + | |
| 177 | +A linha 3 traz todo o breadcrumbs que já foi feito anteriormente para a página corrente, e a linha 4 acrescenta um novo elemento na lista dos breadcrumbs. Observe que você não precisa se preocupar em dizer qual página está sendo exibida e nem costomizar nenhum HTML. A template tag já faz tudo isso por você. Você só precisa dar um nome para o link, chamar a ulr da página e passar algum parâmetro para a ulr(caso for preciso). | |
| 178 | + | |
| 179 | +```3 - courses > templates > course > view.html``` | |
| 180 | +O arquivo 3 é o template de um curso específico, e ele herda do template ```2```. | |
| 181 | +```python | |
| 182 | +{% block breadcrumbs %} | |
| 183 | + | |
| 184 | + {{ block.super }} | |
| 185 | + {% breadcrumb course 'course:view' course.slug %} | |
| 186 | + | |
| 187 | +{% endblock %} | |
| 188 | +``` | |
| 189 | +Repare que o primeiro parâmetro agora é uma variavel do template que representa o nome do curso, e o terceiro parâmetro é um argumento para a url(eles não precisam de aspas). | |
| 190 | + | |
| 191 | +```4 - courses > templates > subject > create.html``` | |
| 192 | +O arquivo ```4``` é o template de criar uma disciplica e ele herda do template ```3``` | |
| 193 | + | |
| 194 | +```python | |
| 195 | +1 {% block breadcrumbs %} | |
| 196 | +2 {{ block.super }} | |
| 197 | +3 {% breadcrumb 'Create subject' 'course:create_subject' course.slug %} | |
| 198 | +4 {% endblock breadcrumbs %} | |
| 199 | +``` | |
| 200 | +Feito isso o breadcrumbs da página 'Criar disciplina' fica da seguinte forma: | |
| 201 | + [Home]() / [Cursos]() / [Nome do Curso]() / Criar disciplina | |
| 202 | + | |
| 203 | + | |
| 125 | 204 | |
| 126 | 205 | |
| 127 | 206 | ## Link's úteis | ... | ... |
courses/templates/course/update.html
courses/templates/course/view.html
courses/templates/subject/create.html