From 5549a9fc78c9a86b079f5b3153d8a3ad8e23cc47 Mon Sep 17 00:00:00 2001 From: Vaida Plankyte Date: Tue, 22 Aug 2017 13:54:08 +0100 Subject: [PATCH] docs: Move template section from translating.md to html-templates. Fixes #1649. --- docs/architecture-overview.md | 3 +- docs/directory-structure.md | 2 +- docs/html-templates.md | 91 +++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/translating.md | 22 +++++---- 5 files changed, 107 insertions(+), 12 deletions(-) create mode 100644 docs/html-templates.md diff --git a/docs/architecture-overview.md b/docs/architecture-overview.md index 479603759f..7a86b35951 100644 --- a/docs/architecture-overview.md +++ b/docs/architecture-overview.md @@ -128,7 +128,8 @@ live-rendering HTML from JavaScript for things like the main message feed. For more details on the frontend, see our documentation on -[templates and translation](translating.html), +[translation](translating.html), +[templates](html-templates.html), [directory structure](directory-structure.html), and [the static asset pipeline](front-end-build-process.html). diff --git a/docs/directory-structure.md b/docs/directory-structure.md index 6e31040537..6ecac2e76c 100644 --- a/docs/directory-structure.md +++ b/docs/directory-structure.md @@ -41,7 +41,7 @@ paths will be familiar to Django developers. ### HTML Templates -See [our translating docs](translating.html) for details on Zulip's +See [our docs](html-templates.html) for details on Zulip's templating systems. * `templates/zerver/` For [Jinja2](http://jinja.pocoo.org/) templates diff --git a/docs/html-templates.md b/docs/html-templates.md new file mode 100644 index 0000000000..0d68fbbd8d --- /dev/null +++ b/docs/html-templates.md @@ -0,0 +1,91 @@ +# HTML templates + +### Behavior + +* Templates are automatically recompiled in development when the file +is saved; a refresh of the page should be enough to display the latest +version. You might need to do a hard refresh, as some browsers cache +webpages. + +* Variables can be used in templates. The variables available to the +template are called the **context**. Passing the context to the HTML +template sets the values of those variables to the value they were +given in the context. The sections below contain specifics on how the +context is defined and where it can be found. + +## Backend + +For text generated in the backend, including logged-out ("portico") +pages and the webapp's base content, we use the [Jinja2][] template +engine (files in `templates/zerver`). + +The syntax for using conditionals and other common structures can be +found [here][jconditionals]. + +The context for Jinja2 templates is assembled from a few places: + +* `zulip_default_context` in `zerver/context_processors.py`. This is +the default context available to all Jinja2 templates. + +* As an argument in the `render` call in the relevant function that +renders the template. For example, if you want to find the context +passed to `index.html`, you can do: + +``` +$ git grep zerver/index.html '*.py' +zerver/views/home.py: response = render(request, 'zerver/index.html', +``` + +The next line in the code being the context definition. + +* `zproject/urls.py` for some fairly static pages that are rendered +using `TemplateView`, for example: + +``` +url(r'^config-error/google$', TemplateView.as_view( + template_name='zerver/config_error.html',), + {'google_error': True},), +``` + +## Frontend + +For text generated in the frontend, live-rendering HTML from +JavaScript for things like the main message feed, we use the +[Handlebars][] template engine (files in `static/templates/`) and +sometimes work directly from JavaScript code (though as a policy +matter, we try to avoid generating HTML directly in JavaScript +wherever possible). + +The syntax for using conditionals and other common structures can be +found [here][hconditionals]. + +There's no equivalent of `zulip_default_context` for the Handlebars +templates. + +In order to find the context definition, you should grep without using +the file extension. For example, to find where +`invite_subscription.handlebars` is rendered, you should run something +like this: + +``` +$ git grep "render('invite_subscription" 'static/js' +frontend_tests/node_tests/templates.js: var html = render('invite_subscription', args); +static/js/invite.js: $('#streams_to_add').html(templates.render('invite_subscription', {streams: streams})); +``` + +The second argument to `templates.render` is the context. + +### Translation + +All user-facing strings (excluding pages only visible to sysadmins or +developers) should be tagged for [translation][]. + +[Jinja2]: http://jinja.pocoo.org/ +[Handlebars]: http://handlebarsjs.com/ +[trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n +[i18next]: http://i18next.com +[official]: http://i18next.com/translate/pluralSimple/ +[helpers]: http://handlebarsjs.com/block_helpers.html +[jconditionals]: http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures +[hconditionals]: http://handlebarsjs.com/block_helpers.html +[translation]: translating.html diff --git a/docs/index.rst b/docs/index.rst index 8c79fa5a10..7336b3fcd6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -147,6 +147,7 @@ Contents: email analytics translating + html-templates client logging release-checklist diff --git a/docs/translating.md b/docs/translating.md index 3ba055dfcb..fcb805085e 100644 --- a/docs/translating.md +++ b/docs/translating.md @@ -205,12 +205,17 @@ resource files are located at These files are uploaded to [Transifex][], where they can be translated. +## HTML Templates + +Zulip makes use of the [Jinja2][] templating system for the backend +and [Handlebars][] for the frontend. Our [HTML templates][html-templates] +documentation includes useful information on the syntax and +behavior of these systems. + ## Backend translations -All user-facing text in the Zulip UI should be generated by an HTML -template so that it can be translated. For text generated in the -backend, including logged-out ("portico") pages and the webapp's base -content, we use the [Jinja2][] template engine. +All user-facing text in the Zulip UI should be generated by an Jinja2 HTML +template so that it can be translated. To mark a string for translation in a Jinja2 template, you can use the `_()` function in the templates like this: @@ -258,11 +263,8 @@ Zulip linter (`tools/lint`) checks for correct usage. ## Frontend translations -For text generated in the frontend, live-rendering HTML from -JavaScript for things like the main message feed, we use the -[Handlebars][] template engine and sometimes work directly from -JavaScript code. In both cases, we use the [i18next][] library -for translations. +We use the [i18next][] library for frontend translations when dealing +with [Handlebars][] templates or JavaScript. To mark a string translatable in JavaScript files, pass it to the `i18n.t` function. @@ -355,7 +357,6 @@ The rules for plurals are same as for JavaScript files. You just have to declare the appropriate keys in the resource file and then include the `count` in the context. - ## Transifex config The config file that maps the resources from Zulip to Transifex is @@ -392,3 +393,4 @@ organizations from the command line. [resource]: http://i18next.com/translate/ [Transifex]: https://transifex.com [transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc +[html-templates]: html-templates.html