Guia do Breadcrumbs [EN-US] #459

ailsoncgt
1 parent 281c760a
Showing 1 changed file with 110 additions and 0 deletions Show diff stats
README.md
@@ -169,6 +169,7 @@ A linha 4, é onde a mágica acontece. É o breadcrumb da página em si.
 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.
  
 ***OBS:*** Se a url tivesse um parâmetro, ele devia ser passado como um terceiro argumento da template tag.
+
 ***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'
  
 ```2 - courses > templates > course > index.html```
@@ -223,6 +224,115 @@ Feito isso o breadcrumbs da página &#39;Criar disciplina&#39; fica da seguinte forma:
  
  
  [Home]() / [Cursos]() / [Nome do Curso]() / Criar disciplina 
+ 
+
+[EN-SU]
+**Breadcrumbs** reduce the number of actions a user needs to take to reach a top-level page and improve the level of reachability of sections and pages.
+
+In amadeus we are using lib [django-bootstrap-breadcrumbs](http://django-bootstrap-breadcrumbs.readthedocs.io/en/latest/) to offer this facility to our users.
+
+
+**How to use:**
+
+
+The package is already installed in the project. It is in the list of dependencies that are in the `requirements.txt` file, which has already been installed previously. So to use lib in a template, you just need to load the tag: ```{% load django_bootstrap_breadcrumbs %}```
+
+The package assumes that you have a good organization of urls in your project so that it can work as expected. It works the base inheritance of templates, how so?
+
+In the file ```core > templates > base.html``` there is a block called ***breadcrumbs***, which is the block that should be changed by the templates that inherit from ``` base.html```. The other block coming soon ***render_breadcrumbs*** is the block responsible for rendering all the HTML that is generated by the enterior block, and it should only be used once.
+ALL files that inherit from the template ```base.html``` or from another template that inherited from it, should implement the block ***breadcrumbs***.
+
+
+***Example***
+
+
+As our dashboard starts in the app ```app```, it is in this app that was made the first inheritance of the block ***breadcrumbs*** and from there all the apps extend from the templates of this app.
+Let's illustrate an example of breadcrumbs that goes up the page to create a subject within a course:
+
+```1 - home.html```
+
+
+The ```1``` file is found in the ```app``` app and it inherits from the ``` base.html``` template
+
+
+``` Python
+1  {% block breadcrumbs %}
+2
+3       {% clear_breadcrumbs %}
+4       {% breadcrumb 'Home' 'app: index' %}
+5
+6  {% endblock %}
+7
+8  {% block render_breadcrumbs %}
+9      {% render_breadcrumbs %}
+10 {% endblock %}
+```
+
+Line 3 is responsible for 'clearing' all previously made breadcrumbs, that is, if there were any breadcrumbs in the trmplate inherited by ``` home.html```, it will not exist from that template. So it is recommended to use this tag only in the breadcrumbs root template, egg: na home.
+
+Line 4, is where magic happens. It is the breadcrumb of the page itself.
+The first parameter of the template tag: 'Home' is the text that will be linked (when you are on another page). It can be a text, which has to be enclosed in quotation marks, for example 'Home', or it can be a template variable that in this case does not need quotation marks. The second parameter is the url of the page in which the template in question is going to be displayed, that is, it calls its own ulr, as expected.
+
+***NOTE:*** If the url had a parameter, it should be passed as a third argument of the template tag.
+
+***NOTE 2:*** Line 9 only needs to be called once and should be in the template home, egg: non-root templates of breadcrumbs do not need to subscribe to the 'render_breadcrumbs'
+
+```2 - courses > templates > course > index.html```
+
+
+The ```2``` file is the index of the ```courses``` app and it inherits the ```1``` template.
+
+
+``` python
+1 {% block breadcrumbs %}
+2
+3     {{ block.super }}
+4     {% breadcrumb 'Courses' 'course: manage' %}
+5
+6 {% endblock %}
+```
+
+Line 3 brings all the breadcrumbs that were previously made to the current page, and line 4 adds a new element to the breadcrumbs list. Note that you do not have to worry about which page is being displayed or costomising any HTML. The template tag does all this for you. You just need to give the link a name, call the ulr of the page and pass some parameter to the ulr (if necessary).
+
+```3 - courses > templates > course > view.html```
+
+
+File 3 is the template for a specific course, and it inherits from the ```2``` template.
+
+
+``` python
+1 {% block breadcrumbs %}
+2
+3     {{ block.super }}
+4     {% breadcrumb course 'course: view' course.slug %}
+6 {% endblock %}
+```
+
+Notice that the first parameter is now a template variable that represents the course name, and the third parameter is an argument to the url (they do not need quotation marks).
+
+```4 - courses > templates > subject > create.html```
+
+
+The ```4``` file is the template for creating a discipline and it inherits from the ```3``` template.
+
+
+
+``` python
+1 {% block breadcrumbs%}
+2     {{ block.super }}
+3     {% breadcrumb 'Create subject' 'course: create_subject' course.slug %}
+4 {% endblock breadcrumbs %}
+```
+
+Once this is done, the breadcrumbs of the 'Create discipline' page is as follows:
+
+
+[Home]() / [Courses]() / [Course Name]() / Create Subject
+
+
+
+
+
...	...	@@ -169,6 +169,7 @@ A linha 4, é onde a mágica acontece. É o breadcrumb da página em si.
169	169	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.
170	170
171	171	*OBS:* Se a url tivesse um parâmetro, ele devia ser passado como um terceiro argumento da template tag.
	172	+
172	173	*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'
173	174
174	175	```2 - courses > templates > course > index.html```
...	...	@@ -223,6 +224,115 @@ Feito isso o breadcrumbs da página 'Criar disciplina' fica da seguinte forma:
223	224
224	225
225	226	[Home]() / [Cursos]() / [Nome do Curso]() / Criar disciplina
	227	+
	228	+
	229	+[EN-SU]
	230	+Breadcrumbs reduce the number of actions a user needs to take to reach a top-level page and improve the level of reachability of sections and pages.
	231	+
	232	+In amadeus we are using lib [django-bootstrap-breadcrumbs](http://django-bootstrap-breadcrumbs.readthedocs.io/en/latest/) to offer this facility to our users.
	233	+
	234	+
	235	+How to use:
	236	+
	237	+
	238	+The package is already installed in the project. It is in the list of dependencies that are in the `requirements.txt` file, which has already been installed previously. So to use lib in a template, you just need to load the tag: ```{% load django_bootstrap_breadcrumbs %}```
	239	+
	240	+The package assumes that you have a good organization of urls in your project so that it can work as expected. It works the base inheritance of templates, how so?
	241	+
	242	+In the file ```core > templates > base.html``` there is a block called *breadcrumbs, which is the block that should be changed by the templates that inherit from ``` base.html```. The other block coming soon render_breadcrumbs* is the block responsible for rendering all the HTML that is generated by the enterior block, and it should only be used once.
	243	+ALL files that inherit from the template ```base.html``` or from another template that inherited from it, should implement the block *breadcrumbs*.
	244	+
	245	+
	246	+*Example*
	247	+
	248	+
	249	+As our dashboard starts in the app ```app```, it is in this app that was made the first inheritance of the block *breadcrumbs* and from there all the apps extend from the templates of this app.
	250	+Let's illustrate an example of breadcrumbs that goes up the page to create a subject within a course:
	251	+
	252	+```1 - home.html```
	253	+
	254	+
	255	+The ```1``` file is found in the ```app``` app and it inherits from the ``` base.html``` template
	256	+
	257	+
	258	+``` Python
	259	+1 {% block breadcrumbs %}
	260	+2
	261	+3 {% clear_breadcrumbs %}
	262	+4 {% breadcrumb 'Home' 'app: index' %}
	263	+5
	264	+6 {% endblock %}
	265	+7
	266	+8 {% block render_breadcrumbs %}
	267	+9 {% render_breadcrumbs %}
	268	+10 {% endblock %}
	269	+```
	270	+
	271	+Line 3 is responsible for 'clearing' all previously made breadcrumbs, that is, if there were any breadcrumbs in the trmplate inherited by ``` home.html```, it will not exist from that template. So it is recommended to use this tag only in the breadcrumbs root template, egg: na home.
	272	+
	273	+Line 4, is where magic happens. It is the breadcrumb of the page itself.
	274	+The first parameter of the template tag: 'Home' is the text that will be linked (when you are on another page). It can be a text, which has to be enclosed in quotation marks, for example 'Home', or it can be a template variable that in this case does not need quotation marks. The second parameter is the url of the page in which the template in question is going to be displayed, that is, it calls its own ulr, as expected.
	275	+
	276	+*NOTE:* If the url had a parameter, it should be passed as a third argument of the template tag.
	277	+
	278	+*NOTE 2:* Line 9 only needs to be called once and should be in the template home, egg: non-root templates of breadcrumbs do not need to subscribe to the 'render_breadcrumbs'
	279	+
	280	+```2 - courses > templates > course > index.html```
	281	+
	282	+
	283	+The ```2``` file is the index of the ```courses``` app and it inherits the ```1``` template.
	284	+
	285	+
	286	+``` python
	287	+1 {% block breadcrumbs %}
	288	+2
	289	+3 {{ block.super }}
	290	+4 {% breadcrumb 'Courses' 'course: manage' %}
	291	+5
	292	+6 {% endblock %}
	293	+```
	294	+
	295	+Line 3 brings all the breadcrumbs that were previously made to the current page, and line 4 adds a new element to the breadcrumbs list. Note that you do not have to worry about which page is being displayed or costomising any HTML. The template tag does all this for you. You just need to give the link a name, call the ulr of the page and pass some parameter to the ulr (if necessary).
	296	+
	297	+```3 - courses > templates > course > view.html```
	298	+
	299	+
	300	+File 3 is the template for a specific course, and it inherits from the ```2``` template.
	301	+
	302	+
	303	+``` python
	304	+1 {% block breadcrumbs %}
	305	+2
	306	+3 {{ block.super }}
	307	+4 {% breadcrumb course 'course: view' course.slug %}
	308	+6 {% endblock %}
	309	+```
	310	+
	311	+Notice that the first parameter is now a template variable that represents the course name, and the third parameter is an argument to the url (they do not need quotation marks).
	312	+
	313	+```4 - courses > templates > subject > create.html```
	314	+
	315	+
	316	+The ```4``` file is the template for creating a discipline and it inherits from the ```3``` template.
	317	+
	318	+
	319	+
	320	+``` python
	321	+1 {% block breadcrumbs%}
	322	+2 {{ block.super }}
	323	+3 {% breadcrumb 'Create subject' 'course: create_subject' course.slug %}
	324	+4 {% endblock breadcrumbs %}
	325	+```
	326	+
	327	+Once this is done, the breadcrumbs of the 'Create discipline' page is as follows:
	328	+
	329	+
	330	+[Home]() / [Courses]() / [Course Name]() / Create Subject
	331	+
	332	+
	333	+
	334	+
	335	+
226	336
227	337
228	338
...	...