Changes between Initial Version and Version 1 of TranslationRu/WikiMacros

Timestamp:

Sep 16, 2008, 5:00:03 AM (16 years ago)

Author:

kossmak@…

Comment:

—

TranslationRu/WikiMacros

@@ +1 @@
+= Trac макросы =
+
+[[PageOutline]]
+
+En-Version: WikiMacros
+
+Trac макросы — плагины для расширения Trac движка с помощью специальных функций, написанных на Python. Макрос вставляет динамические HTML данные в любом контексте, поддерживающем Wiki-форматирование.
+
+Другой тип макросов — WikiProcessors. Обычно имеют дело с альтернативными форматами разметки и представления больших блоков информации (как подсветка исходных кодов).
+
+== Использование макросов ==
+
+Вызов макроса заключается в двойные квадратные скобки. Как и все функции Python, макросы могут принимать аргументы, перечисленные через запятую в круглых скобках после имени макроса.
+
+Trac макросы могут быть также написаны как TracPlugins. Это позволяет им некотороые дополнительные возможности, которых обычные макросы не имеют, например, непосредственный доступ к HTTP запросу.
+
+== Пример ==
+
+Список из 3 страниц, начинающихся с 'Trac', которые недавно изменялись:
+{{{
+ [[RecentChanges(Trac,3)]]
+}}}
+
+Отображается:
+ [[RecentChanges(Trac,3)]]
+
+== Доступные макросы ==
+
+''Отметьте, что следующий список будет содержать макро-документацию, только если вы не используете `OO` оптимизацию, или не установлена опция `PythonOptimize` в [wiki:TracModPython mod_python].''
+
+{{{
+[[MacroList]]
+}}}
+[[MacroList]]
+
+== Макросы в сети ==
+
+Сайт [http://trac-hacks.org/ Trac Hacks] содержит большую коллекцию макросов и других Trac [TracPlugins plugins] плагинов, созданных Trac-сообществом. Если вы ищете или написали новый макрос, которым хотите поделиться с другими, пожалуйста, не стесняйтесь заходить на этот сайт.
+
+== Разработка своих макросов ==
+
+Макросы, подобно самому Trac, пишутся на [http://python.org/ языке программирования Python].
+
+Для дополнительной информации о разработке макроса, см. TracDev на главной странице проекта.
+{{{
+!#comment
+[wiki:TracDev development resources] 
+}}}
+
+== Реализация ==
+Здесь 2 простых примера, как создавать макрос для [wiki:0.11 Trac 0.11], различия между старым и новым стилем макросов можно посмотреть в исходнике source:trunk/sample-plugins/Timestamp.py, а также в source:trunk/wiki-macros/README.
+
+=== Макрос без аргументов ===
+
+Этот код должен быть сохранен как `TimeStamp.py`, чтобы использоваться в Trac по имени макроса.
+{{{
+#!python
+from datetime import datetime
+# Note: since Trac 0.11, datetime objects are used internally
+
+from genshi.builder import tag
+
+from trac.util.datefmt import format_datetime, utc
+from trac.wiki.macros import WikiMacroBase
+
+class TimestampMacro(WikiMacroBase):
+    """Inserts the current time (in seconds) into the wiki page."""
+
+    revision = "$Rev$"
+    url = "$URL$"
+
+    def expand_macro(self, formatter, name, args):
+        t = datetime.now(utc)
+        return tag.b(format_datetime(t, '%c'))
+}}}
+
+=== Макрос с аргументами ===
+Этот код должен быть сохранен как `HelloWorld.py` (в папке plugins/).
+{{{
+#!python
+from trac.wiki.macros import WikiMacroBase
+
+class HelloWorldMacro(WikiMacroBase):
+    """Simple HelloWorld macro.
+
+    Note that the name of the class is meaningful:
+     - it must end with "Macro"
+     - what comes before "Macro" ends up being the macro name
+
+    The documentation of the class (i.e. what you're reading)
+    will become the documentation of the macro, as shown by
+    the !MacroList macro (usually used in the WikiMacros page).
+    """
+
+    revision = "$Rev$"
+    url = "$URL$"
+
+    def expand_macro(self, formatter, name, args):
+        """Return some output that will be displayed in the Wiki content.
+
+        `name` is the actual name of the macro (no surprise, here it'll be
+        `'HelloWorld'`),
+        `args` is the text enclosed in parenthesis at the call of the macro.
+          Note that if there are ''no'' parenthesis (like in, e.g.
+          [[HelloWorld]]), then `args` is `None`.
+        """
+        return 'Hello World, args = ' + unicode(args)
+    
+    # Note that there's no need to HTML escape the returned data,
+    # as the template engine (Genshi) will do it for us.
+}}}
+
+
+=== {{{expand_macro}}} details ===
+{{{expand_macro}}} должно возвращать также простую строку Python, которая будет интерпретирована как HTML, или предпочтительный объект разметки (используйте {{{from trac.util.html import Markup}}}). {{{Markup(string)}}} просто вставляет строку, которую интерпретатор преобразует в HTML строку как есть. Также вам может понадобиться использовать импорт Formatter {{{from trac.wiki import Formatter}}}.
+
+Если ваш макрос создает wiki-разметку вместо HTML, вы можете конвертировать ее в HTML примерно так:
+{{{
+#!python
+  text = "whatever wiki markup you want, even containing other macros"
+  # Convert Wiki markup to HTML, new style
+  out = StringIO()
+  Formatter(self.env, formatter.context).format(text, out)
+  return Markup(out.getvalue())
+}}}