Changes between Version 1 and Version 2 of WikiMacros

Timestamp:

11/04/11 12:44:56 (19 months ago)

Author:

trac

Comment:

--

WikiMacros

@@ -1 @@
-= Macros na Wiki =
-[[TracGuideToc]]
-Macros no Trac são plugins que extendem a funcionalidade do Trac com 'funções' escritas em Python.Um macro insere dinamicamente um dado HTML em qualquer contexto suportado pelo WikiFormatting.
+= Trac Macros =
 
-Outro tipo de macro são os WikiProcessors. Eles tipicamente são alternativas a formatações de alto nível e representações de grandes blocos de informação (como um código-fonte em destaque).
+[[PageOutline]]
 
-Veja também: WikiProcessors.
+Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting.
 
-== Usando Macros ==
-As chamadas de macros são atreladas a ''[]''. Como nas funções do Python, macros também podem ter argumentos,usando-se uma lista separada por vírgulas dentro de parênteses.
+Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting).
 
-=== Exemplos ===
+== Using Macros ==
+Macro calls are enclosed in two ''square brackets''. Like Python functions, macros can also have arguments, a comma separated list within parentheses.
+
+Trac macros can also be written as TracPlugins. This gives them some capabilities that macros do not have, such as being able to directly access the HTTP request.
+
+=== Example ===
+
+A list of 3 most recently changed wiki pages starting with 'Trac':
 
 {{{
- [[Timestamp]]
+ [[RecentChanges(Trac,3)]]
 }}}
-Mostrará:
- [[Timestamp]]
 
-{{{
- [[HelloWorld(Testing)]]
-}}}
-Mostrará:
- [[HelloWorld(Testing)]]
+Display:
+ [[RecentChanges(Trac,3)]]
+
+== Available Macros ==
+
+''Note that the following list will only contain the macro documentation if you've not enabled `-OO` optimizations, or not set the `PythonOptimize` option for [wiki:TracModPython mod_python].''
+
+[[MacroList]]
+
+== Macros from around the world ==
+
+The [http://trac-hacks.org/ Trac Hacks] site provides a wide collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you're looking for new macros, or have written one that you'd like to share with the world, please don't hesitate to visit that site.
+
+== Developing Custom Macros ==
+Macros, like Trac itself, are written in the [http://python.org/ Python programming language].
+
+For more information about developing macros, see the [trac:TracDev development resources] on the main project site.
 
 
-== Macros Disponiníveis ==
-Macros ainda são novidades e a lista de macros disponíveis (e distribuidos) não é muito extensa. Em futuras versões do Trac, nós esperamos construir uma biblioteca bem útil de macros e vamos agradecidamente incluir contribuições de macros (veja abaixo).
+== Implementation ==
 
- * '''!HelloWorld''' -- Um exemplo de macro, muito útil para se aprender a escrever macros.
- * '''Timestamp''' -- Insere a data e a hora atual.
+Here are 2 simple examples showing how to create a Macro with Trac 0.11. 
 
+Also, have a look at [trac:source:tags/trac-0.11/sample-plugins/Timestamp.py Timestamp.py] for an example that shows the difference between old style and new style macros and at the [trac:source:tags/trac-0.11/wiki-macros/README macros/README] which provides a little more insight about the transition.
 
-----
+=== Macro without arguments ===
+It should be saved as `TimeStamp.py` (in the TracEnvironment's `plugins/` directory) as Trac will use the module name as the Macro name.
+{{{
+#!python
+from datetime import datetime
+# Note: since Trac 0.11, datetime objects are used internally
 
+from genshi.builder import tag
 
-== Macros através do mundo ==
-A página do [http://projects.edgewall.com/trac/ Projeto Trac] tem um seção dedicada para macros contribuídos pelos usuários [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar]. Se você está procurando por novos macros ou escreveu alguns novos , não hesite em adicioná-lo a página wiki do http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar].
+from trac.util.datefmt import format_datetime, utc
+from trac.wiki.macros import WikiMacroBase
 
-  http://projects.edgewall.com/trac/wiki/MacroBazaar
+class TimeStampMacro(WikiMacroBase):
+    """Inserts the current time (in seconds) into the wiki page."""
 
+    revision = "$Rev$"
+    url = "$URL$"
 
-----
-
-
-== Desenvolvendo Novos Macros ==
-Macros, como o Trac, são escritos usando-se [http://www.python.org/ Linguagem de Programação Python]. Eles são compostos de simples módulos, identificados pelo nome do arquivo e que devem conter um único ''ponto de entrada'' nas funções.o Trac irá mostrar o dado inserido dentro do HTML quando o mesmo for chamado.
-
-
-É muito fácil aprender a partir de um exemplo:
-{{{
-# MeuMacro.py -- O macro mais simple do mundo
-def execute(hdf, args, env):
-    return "Oi mundo chamado com os argumentos: %s" % args
+    def expand_macro(self, formatter, name, args):
+        t = datetime.now(utc)
+        return tag.b(format_datetime(t, '%c'))
 }}}
 
-=== Tópicos Avançados: Macros embutidos em Templates ===
-Para usuários avançados, macros também pode renderizar a saída em HDF,  para serem renderizados para HTML usando-se templates clearsilver - como na maioria das saídas do Trac. Em resumo, isto permite mais genéricos e bem desenvolvidos macros avançados.
+=== Macro with arguments ===
+It should be saved as `HelloWorld.py` (in the TracEnvironment's `plugins/` directory) as Trac will use the module name as the Macro name.
+{{{
+#!python
+from trac.wiki.macros import WikiMacroBase
 
-Macros ganham acesso direto a principal árvore do HDF e podem manipulá-las livremente.
+class HelloWorldMacro(WikiMacroBase):
+    """Simple HelloWorld macro.
 
-Exemplo:
-{{{
-def execute(hdf, args, env):
-    # o hdf atual só é setado quando o macro é chamado
-    # de uma página wiki
-    if hdf:
-        hdf.setValue('wiki.macro.greeting', 'Olá Mundo')
-        
-    # os argumentos serão nulos se o macro for chamado sem parênteses.
-    args = args or 'Sem argumentos'
-    return 'Olá mundo, args = ' + args
+    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.
 }}}
 
 
-Você também pode usar o objeto ambiente (env) para acessar um dado de configuração.
+=== {{{expand_macro}}} details ===
+{{{expand_macro}}} should return either a simple Python string which will be interpreted as HTML, or preferably a Markup object (use {{{from trac.util.html import Markup}}}).  {{{Markup(string)}}} just annotates the string so the renderer will render the HTML string as-is with no escaping. You will also need to import Formatter using {{{from trac.wiki import Formatter}}}.
 
+If your macro creates wiki markup instead of HTML, you can convert it to HTML like this:
 
-Exemplo.
 {{{
-def execute(hdf, txt, env):
-    return env.get_config('trac', 'repository_dir')
+#!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())
 }}}
-
-
-----
-Veja também:  WikiProcessors, WikiFormatting, TracGuide