Changes between Version 1 and Version 2 of WikiMacros

Timestamp:

Mar 21, 2004, 8:12:37 AM (20 years ago)

Author:

daniel

Comment:

—

WikiMacros

@@ -1 @@
-=  Wiki Macros - Plugins =
+=  Wiki Macros =
+Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. They allow insertion of custom dynamic HTML data in any module supporting WikiFormatting.
 
-Wiki macros is an experimental feature to use custom "plugin" modules to extend the wiki and the WikiFormatting syntax. 
+Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting). See also: WikiProcessors.
 
-JonasBorgstrom commited initial support for it in [167].
+== Available Macros ==
+As of 0.6, macros are still a new feature in Trac, and the list of available (and distributed) macros is 
+admittedly not very impressive. In future Trac releases, we hope to build a library of useful macros, and will of course happily include contributed macros (see below). 
 
-'''For now, macros are considered dangerous and the consequences are unexplored''' - on the other hand, that makes it just '''so''' much more interesting, doesn't it? 
+ * '''!HelloWorld''' -- An example macro, useful for learning how to write macros.
+ * '''Timestamp''' -- Insert the current date and time.
+
+=== Examples ===
+!HelloWorld:
+ [[HelloWorld(Testing)]]
+
+Timestamp:
+ [[Timestamp]]
+
 
 ----
 
-Using a macro, we could pretty easily add support for RestructuredText in Trac. -- DanielLundin
+
+== Macros from around the world ==
+The [http://projects.edgewall.com/trac/ Trac Project] has a section dedicated to user-contributed macros, [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar]. If you're looking for new macros, or have written new ones to share with the world, don't hesitate adding it to the [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar] wiki page.
+
+  http://projects.edgewall.com/trac/wiki/MacroBazaar
+
+
+----
+
+
+== Developing New Macros ==
+Macros, like Trac itself, are written in the [http://www.python.org/ Python programming language]. They are very simple modules, identified by the filename and should contain a single ''entry point'' function. Trac will display the returned data inserted into the HTML where the macro was called.
+
+It's easiest to learn from an example:
+{{{
+# MyMacro.py -- The world's simplest macro
+
+def execute(hdf, args):
+    return "Hello World called with args: %s" % args
+}}}
+
+=== Advanced Topics: Template-enabled Macros ===
+For advanced uses, macros can also render structured output in HDF, to be rendered to HTML using clearsilver templates - like most Trac output. In short, this allows more generic and well-designed advanced macros.
+
+Macros gain direct access to the main HDF tree, and are free to manipulate it. 
+
+Example:
+{{{
+def execute(hdf, args):
+    # Currently hdf is set only when the macro is called
+    # From a wiki page
+    if hdf:
+        hdf.setValue('wiki.macro.greeting', 'Hello World')
+        
+    # args will be null if the macro is called without parentesis.
+    args = args or 'No arguments'
+    return 'Hello World, args = ' + args
+}}}
+
+
+
+----
+See also:  WikiProcessors, WikiFormatting, TracGuide