Changes between Initial Version and Version 1 of EggCookingTutorialTrac0.11

Timestamp:

Jun 3, 2007, 8:37:22 AM (17 years ago)

Author:

Bhuricha Deen Sethanandha

Comment:

--

EggCookingTutorialTrac0.11

@@ +1 @@
+[[TOC]]
+
+= Egg cooking =
+
+Since Trac 0.11, Genshi is used as the new template engine.  Some APIs have also been changed.
+
+This tutorial shows how to make an egg, and load an egg in Trac. In the advanced parts you'll learn how to serve templates and static content from an egg.
+
+You should be familiar with [trac:TracDev/ComponentArchitecture component architecture] and [trac:TracDev/PluginDevelopment plugin development]. This plugin is based on the example in the plugin development article.  Here we extend it a bit further.
+
+== Required items ==
+
+ * ''setuptools>=0.6b1''. For instructions and files see [http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install EasyInstall] page.
+ * '''Trac 0.11'''.  Download it from the [http://projects.edgewall.com/trac/wiki/TracDownload TracDownload] page.
+ * '''Genshi>-0.4'''. Download it from the [http://genshi.edgewall.org/wiki/Download GenshiDownload] page.
+
+== Directories ==
+
+To develop a plugin you need to create a few directories to keep things together.
+
+So let's create following directories:
+{{{
+./helloworld-plugin/
+./helloworld-plugin/helloworld/
+}}}
+
+== Main plugin ==
+
+The first step is to generate the main module for this plugin.  We will construct a simple plugin that will display "Hello world!" on the screen when accessed through the /helloworld URL. The plugin also provides a "Hello" button that is, by default, rendered on the far right in the main navigation bar.
+
+So create ''helloworld.py'' in ''./helloworld-plugin/helloworld/'':
+{{{
+#!python
+# Helloworld plugin
+
+import re
+
+from genshi.builder import tag
+
+from trac.core import *
+from trac.web import IRequestHandler
+from trac.web.chrome import INavigationContributor
+
+class HelloWorldPlugin(Component):
+    implements(INavigationContributor, IRequestHandler)
+
+    # INavigationContributor methods
+    def get_active_navigation_item(self, req):
+        return 'helloworld'
+    
+    def get_navigation_items(self, req):
+        yield ('mainnav', 'helloworld',
+               tag.a('Hello World', href=req.href.helloworld()))
+    
+    # IRequestHandler methods
+    def match_request(self, req):
+        return re.match(r'/helloworld(?:_trac)?(?:/.*)?$', req.path_info)
+    
+    def process_request(self, req):
+        req.send_response(200)
+        req.send_header('Content-Type', 'text/plain')
+        req.end_headers()
+        req.write('Hello world!')
+}}}
+
+To help understand how that works, read the [http://trac.edgewall.org/browser/trunk/trac/web/chrome.py#L108 INavigationContributor] and [http://trac.edgewall.org/browser/trunk/trac/web/api.py#L517 IRequestHandler] interface specifications.
+
+== Make it a module ==
+
+To make the plugin a module, you simply create an ''_''____''_init_''____''_.py'' in ''./helloworld-plugin/helloworld/'':
+{{{
+#!python
+# Helloworld module
+from helloworld import *
+}}}
+
+== Make it an egg ==
+
+Now it's time to make it an egg. For that we need a chicken called ''setup.py'' in ''./helloworld-plugin/'':
+{{{
+#!python
+from setuptools import find_packages, setup
+
+# name can be any name.  This name will be used to create .egg file.
+# name that is used in packages is the one that is used in the trac.ini file.
+# use package name as entry_points
+setup(
+    name='Trachelloworld', version='1.1',
+    packages=find_packages(exclude=['*.tests*']),
+    entry_points = """
+        [trac.plugins]
+        helloworld = helloworld
+    """,
+)
+}}}
+
+You done need to add special [http://peak.telecommunity.com/DevCenter/EggFormats#project-metadata egg metadata] in Trac 0.11.
+
+== First deployment ==
+
+Now try to build the plugin. Run the command {{{python setup.py bdist_egg}}} in the directory where you created it. If everything went OK you should have a .egg file in ''./dist'' directory.
+Copy this ''.egg'' file to ''/[your trac env]/plugins'' directory. 
+
+During development you can run the command {{{python setup.py develop}}} in the directory where you created it.  This way you don't need to do it every time you change the code. Check [trac:TracDev/PluginDevelopment] for more deployment options.
+
+Restart the trac server.  If you're using mod_python you have to restart Apache.
+
+Now you should see ''Hello World'' link at far right in main navigation bar when accessing your site. Click it.
+
+== Aftermath ==
+
+Now you have successfully created your first egg. You can continue further to learn how to use templates in your plugins, and make its output look like other Trac pages.
+
+
+[[TagIt(khundeen)]]