Edgewall Software

Changes between Initial Version and Version 1 of 0.12/TranslationRu/WikiMacros


Ignore:
Timestamp:
Jul 16, 2012, 9:22:15 PM (10 years ago)
Author:
trac
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • 0.12/TranslationRu/WikiMacros

    v1 v1  
     1= Trac макросы =
     2
     3[[PageOutline]]
     4[[TranslatedPages(revison=0)]]
     5
     6Trac макросы — плагины для расширения Trac движка с помощью специальных функций, написанных на Python. Макрос вставляет динамические HTML данные в любом контексте, поддерживающем Wiki-форматирование.
     7
     8Другой тип макросов — WikiProcessors. Обычно имеют дело с альтернативными форматами разметки и представления больших блоков информации (как подсветка исходных кодов).
     9
     10== Использование макросов ==
     11
     12Вызов макроса заключается в двойные квадратные скобки. Как и все функции Python, макросы могут принимать аргументы, перечисленные через запятую в круглых скобках после имени макроса.
     13
     14Trac макросы могут быть также написаны как TracPlugins. Это позволяет им некотороые дополнительные возможности, которых обычные макросы не имеют, например, непосредственный доступ к HTTP запросу.
     15
     16== Пример ==
     17
     18Список из 3 страниц, начинающихся с 'Trac', которые недавно изменялись:
     19{{{
     20 [[RecentChanges(Trac,3)]]
     21}}}
     22
     23Отображается:
     24 [[RecentChanges(Trac,3)]]
     25
     26== Доступные макросы ==
     27
     28''Отметьте, что следующий список будет содержать макро-документацию, только если вы не используете `OO` оптимизацию, или не установлена опция `PythonOptimize` в [wiki:TracModPython mod_python].''
     29
     30{{{
     31[[MacroList]]
     32}}}
     33[[MacroList]]
     34
     35== Макросы в сети ==
     36
     37Сайт [http://trac-hacks.org/ Trac Hacks] содержит большую коллекцию макросов и других Trac [TracPlugins plugins] плагинов, созданных Trac-сообществом. Если вы ищете или написали новый макрос, которым хотите поделиться с другими, пожалуйста, не стесняйтесь заходить на этот сайт.
     38
     39== Разработка своих макросов ==
     40
     41Макросы, подобно самому Trac, пишутся на [http://python.org/ языке программирования Python].
     42
     43Для дополнительной информации о разработке макроса, см. TracDev на главной странице проекта.
     44{{{
     45!#comment
     46[wiki:TracDev development resources]
     47}}}
     48
     49== Реализация ==
     50Здесь 2 простых примера, как создавать макрос для [wiki:0.11 Trac 0.11], различия между старым и новым стилем макросов можно посмотреть в исходнике source:trunk/sample-plugins/Timestamp.py, а также в source:trunk/wiki-macros/README.
     51
     52=== Макрос без аргументов ===
     53
     54Этот код должен быть сохранен как `TimeStamp.py`, чтобы использоваться в Trac по имени макроса.
     55{{{
     56#!python
     57from datetime import datetime
     58# Note: since Trac 0.11, datetime objects are used internally
     59
     60from genshi.builder import tag
     61
     62from trac.util.datefmt import format_datetime, utc
     63from trac.wiki.macros import WikiMacroBase
     64
     65class TimestampMacro(WikiMacroBase):
     66    """Inserts the current time (in seconds) into the wiki page."""
     67
     68    revision = "$Rev$"
     69    url = "$URL$"
     70
     71    def expand_macro(self, formatter, name, args):
     72        t = datetime.now(utc)
     73        return tag.b(format_datetime(t, '%c'))
     74}}}
     75
     76=== Макрос с аргументами ===
     77Этот код должен быть сохранен как `HelloWorld.py` (в папке plugins/).
     78{{{
     79#!python
     80from trac.wiki.macros import WikiMacroBase
     81
     82class HelloWorldMacro(WikiMacroBase):
     83    """Simple HelloWorld macro.
     84
     85    Note that the name of the class is meaningful:
     86     - it must end with "Macro"
     87     - what comes before "Macro" ends up being the macro name
     88
     89    The documentation of the class (i.e. what you're reading)
     90    will become the documentation of the macro, as shown by
     91    the !MacroList macro (usually used in the WikiMacros page).
     92    """
     93
     94    revision = "$Rev$"
     95    url = "$URL$"
     96
     97    def expand_macro(self, formatter, name, args):
     98        """Return some output that will be displayed in the Wiki content.
     99
     100        `name` is the actual name of the macro (no surprise, here it'll be
     101        `'HelloWorld'`),
     102        `args` is the text enclosed in parenthesis at the call of the macro.
     103          Note that if there are ''no'' parenthesis (like in, e.g.
     104          [[HelloWorld]]), then `args` is `None`.
     105        """
     106        return 'Hello World, args = ' + unicode(args)
     107   
     108    # Note that there's no need to HTML escape the returned data,
     109    # as the template engine (Genshi) will do it for us.
     110}}}
     111
     112
     113=== {{{expand_macro}}} details ===
     114{{{expand_macro}}} должно возвращать также простую строку Python, которая будет интерпретирована как HTML, или предпочтительный объект разметки (используйте {{{from trac.util.html import Markup}}}). {{{Markup(string)}}} просто вставляет строку, которую интерпретатор преобразует в HTML строку как есть. Также вам может понадобиться использовать импорт Formatter {{{from trac.wiki import Formatter}}}.
     115
     116Если ваш макрос создает wiki-разметку вместо HTML, вы можете конвертировать ее в HTML примерно так:
     117{{{
     118#!python
     119  text = "whatever wiki markup you want, even containing other macros"
     120  # Convert Wiki markup to HTML, new style
     121  out = StringIO()
     122  Formatter(self.env, formatter.context).format(text, out)
     123  return Markup(out.getvalue())
     124}}}