SimpleTemplate Двигатель Шаблонов

Bottle поставляется с быстрым, мощным и простым в освоении встроенным движком шаблонов, называемым SimpleTemplate или stpl для краткости. Это по умолчанию используется движком в view() и template() помощниках, но также может быть использован как отдельный движок шаблонов общего назначения. В этом документе объясняется синтаксис шаблонов и приводятся примеры для распространённых случаев использования.

Основное Использование API:

SimpleTemplate реализует API BaseTemplate:

>>> from bottle import SimpleTemplate
>>> tpl = SimpleTemplate('Hello {{name}}!')
>>> tpl.render(name='World')
u'Hello World!'

В этом документе мы используем помощник template() в примерах для простоты:

>>> from bottle import template
>>> template('Hello {{name}}!', name='World')
u'Hello World!'

Просто имейте в виду, что компиляция и отображение шаблонов — это два разных действия, даже если помощник template() скрывает этот факт. Шаблоны обычно компилируются только один раз и кешируются внутри, но отображаются много раз с различными ключевыми аргументами.

Синтаксис SimpleTemplate

Python — очень мощный язык, но его чувствительный к отступам синтаксис затрудняет его использование в качестве языка шаблонов. SimpleTemplate устраняет некоторые из этих ограничений и позволяет создавать чистые, удобочитаемые и поддерживаемые шаблоны, сохраняя при этом полный доступ к возможностям, библиотекам и скорости языка Python.

Встроенные выражения

Вы уже узнали об использовании синтаксиса {{...}} из примера «Hello World!» выше, но это не всё: любое выражение Python разрешено в фигурных скобках, если оно приводит к строке или чему-то, что имеет строковое представление:

>>> template('Hello {{name}}!', name='World')
u'Hello World!'
>>> template('Hello {{name.title() if name else "stranger"}}!', name=None)
u'Hello stranger!'
>>> template('Hello {{name.title() if name else "stranger"}}!', name='mArC')
u'Hello Marc!'

Внутреннее выражение Python выполняется во время отображения и имеет доступ ко всем ключевым аргументам, переданным методу SimpleTemplate.render(). HTML-специальные символы автоматически экранируются, чтобы предотвратить атаки типа XSS. Вы можете начать выражение с восклицательного знака, чтобы отключить экранирование для этого выражения:

>>> template('Hello {{name}}!', name='<b>World</b>')
u'Hello &lt;b&gt;World&lt;/b&gt;!'
>>> template('Hello {{!name}}!', name='<b>World</b>')
u'Hello <b>World</b>!'

Встроенный код Python

Двигатель шаблонов позволяет вам встраивать строки или блоки кода Python в ваш шаблон. Строки кода начинаются с %, а блоки кода заключены в <% и %> токены:

% name = "Bob"  # a line of python code
<p>Some plain text in between</p>
<%
  # A block of python code
  name = name.title().strip()
%>
<p>More plain text</p>

Встроенный код Python следует стандартному синтаксису Python, но с двумя дополнительными правилами синтаксиса:

• Отступы игнорируются. Вы можете вставлять любое количество пробелов перед операторами. Это позволяет выравнивать ваш код с окружающим разметкой и может значительно повысить читаемость.
• Блоки, которые обычно отступлены, теперь должны быть явно закрыты с помощью ключевого слова end.

<ul>
  % for item in basket:
    <li>{{item}}</li>
  % end
</ul>

И % и <% токены распознаются только в том случае, если они являются первыми символами, отличными от пробела, в строке. Вы не должны экранировать их, если они появляются в середине текста вашей разметки шаблона. Только если строка текста начинается с одного из этих токенов, вы должны экранировать его обратной косой чертой. В редких случаях, когда сочетание обратной косой черты + токен появляется в начале строки вашей разметки, вы всегда можете помочь себе с литералом строки в выражении в строке:

This line contains % and <% but no python code.
\% This text-line starts with the '%' token.
\<% Another line that starts with a token but is rendered as text.
{{'\\%'}} this line starts with an escaped token.

Если вам приходится много экранировать, подумайте об использовании пользовательских токенов.

Управление пробелами

Блоки кода и строки кода всегда охватывают всю строку. Пробелы перед или после кодового фрагмента удаляются. В вашем шаблоне вы не увидите пустых строк или свисающих пробелов из-за встроенного кода:

<div>
 % if True:
  <span>content</span>
 % end
</div>

Этот фрагмент отображается в чистом и компактном html:

<div>
  <span>content</span>
</div>

Но для вставки кода всё ещё необходимо начинать новую строку, что может не соответствовать вашим желаниям в отрендеренном шаблоне. Чтобы пропустить новую строку перед фрагментом кода, завершите строку текста двойной обратной косой чертой:

<div>\\
 %if True:
<span>content</span>\\
 %end
</div>

В этот раз отрендеренный шаблон будет выглядеть так:

<div><span>content</span></div>

Это работает только непосредственно перед фрагментами кода. Во всех других местах вы можете сами контролировать пробелы и не нуждаетесь в каком-либо специальном синтаксисе.

Функции шаблонов

Каждый шаблон предварительно загружен набором функций, которые помогают в наиболее распространённых случаях использования. Эти функции всегда доступны. Вам не нужно их импортировать или предоставлять самостоятельно. Для всего, что не покрыто здесь, вероятно, существуют хорошие библиотеки Python. Помните, что вы можете import всё, что захотите, в своих шаблонах. В конце концов, они представляют собой программы Python.

include(sub_template, **variables)

Отображает подшаблон с указанными переменными и вставляет полученный текст в текущий шаблон. Функция возвращает словарь, содержащий локальные переменные, переданные или определённые внутри подшаблона:

% include('header.tpl', title='Page Title')
Page Content
% include('foother.tpl')

rebase(name, **variables)

Помечает текущий шаблон для последующего включения в другой шаблон. После отображения текущего шаблона его результирующий текст хранится в переменной с именем base и передаётся базовому шаблону, который затем отображается. Это может быть использовано для wrap шаблона с окружающим текстом или для имитации функции наследования, встречающейся в других движках шаблонов:

% rebase('base.tpl', title='Page Title')
<p>Page Content ...</p>

Это может быть комбинировано со следующим base.tpl:

<html>
<head>
  <title>{{title or 'No title'}}</title>
</head>
<body>
  {{base}}
</body>
</html>

Доступ к неопределённым переменным в шаблоне вызывает NameError и немедленно останавливает отображение. Это стандартное поведение Python и ничего нового, но обычный Python не предоставляет лёгкого способа проверки доступности переменной. Это быстро становится раздражающим, если вы хотите поддерживать гибкие входные данные или использовать один и тот же шаблон в различных ситуациях. Эти функции могут помочь:

defined(name)

Возвращает True, если переменная определена в текущем пространстве имен шаблона, и False в противном случае.

get(name, default=None)

Возвращает переменную или значение по умолчанию.

setdefault(name, default)

Если переменная не определена, создайте её со значением по умолчанию. Возвращает переменную.

Вот пример, который использует все три функции для реализации необязательных переменных шаблонов различными способами:

% setdefault('text', 'No Text')
<h1>{{get('title', 'No Title')}}</h1>
<p> {{ text }} </p>
% if defined('author'):
  <p>By {{ author }}</p>
% end

API SimpleTemplate

class SimpleTemplate(source=None, name=None, lookup=[], encoding='utf8', **settings) [source]

render(*args, **kwargs) [source]

Отображает шаблон, используя ключевые аргументы в качестве локальных переменных.