1
2
3 """TurboGears controller and widgets for feed handling.
4
5 Turbofeeds is a TurboGears_ 1 extension which provides support for generating
6 RSS and Atom feeds and matching display widgets.
7
8 TurboFeeds was formerly the ``feed`` sub-package of the main TurboGears
9 distribution. It was extracted from the TG core to ease updating, enhancing,
10 and maintaining both projects.
11
12 TurboFeeds is mostly backwards-compatible with the ``turbogears.feed``
13 package, but has lots of fixes and a few new features, most importantly support
14 for Genshi templates. It works with both the TurboGears 1.x and the 1.1 branch.
15
16
17 Installation
18 ------------
19
20 To install TurboFeeds from the Cheeseshop_ use `easy_install`_::
21
22 [sudo] easy_install TurboFeeds
23
24 This requires the setuptools_ package to be installed. If you have not done so
25 already, download the `ez_setup.py`_ script and run it to install setuptools.
26
27 If you want to get the latest development version, you can check out the
28 trunk from the `Subversion repository`_ with::
29
30 svn co http://svn.turbogears.org/projects/TurboFeeds/trunk TurboFeeds
31
32 For bug reports and feature requests, please go to the TurboGears trac at
33 http://trac.turbogears.org/.
34
35 To open a ticket, you'll need a trac account. Please select "TurboFeeds" as the
36 ticket component.
37
38
39 Usage
40 -----
41
42 Controller::
43
44 from turbogears import controllers, expose
45 from turbofeeds import FeedController, FeedHeadLinks, FeedLinks
46
47 class MyFeedController(FeedController):
48 def get_feed_data(self, **kwargs):
49 entries = []
50 # Fill ``entries`` with dicts containing at least items for:
51 #
52 # title, link, summary and published
53 #
54 # For example, supposing ``entry`` is a database object
55 # representing a blog article:
56 entries.append(dict(
57 title = entry.title,
58 author = dict(name = entry.author.display_name,
59 email = entry.author.email_address),
60 summary = entry.post[:30],
61 published = entry.published,
62 updated = entry.updated or entry.published,
63 link = 'http://blog.foo.org/article/%s' % entry.id
64 ))
65 return dict(entries=entries)
66
67 class Root(controllers.RootController):
68 feed = MyFeedController(
69 base_url = '/feed',
70 title = "my fine blog",
71 link = "http://blog.foo.org",
72 author = dict(name="John Doe", email="john@foo.org"),
73 id = "http://blog.foo.org",
74 subtitle = "a blog about turbogears"
75 )
76 feedlheadinks = FeedHeadLinks(controller=feed)
77 feedlinks = FeedLinks(controller=feed,
78 title = "Click link to access the feed in %(type)s format")
79
80 @expose('.templates.mypage')
81 def mypage(self):
82 return dict(
83 feedheadlinks=self.feedheadlinks,
84 feedlinks=self.feedlinks)
85
86 Template::
87
88 <head>
89 ${feadheadlinks()}
90 ...
91 </head>
92 <body>
93 <h2>Feed links</h2>
94 ${feedlinks('%(type)s feed', url_params=dict(format='full'))}
95 ...
96 </body>
97
98
99 Documentation
100 -------------
101
102 The TurboFeeds source is thoroughly documented with doc strings.
103 The source distribution comes with epydoc-generated `API documentation`_
104 included.
105
106 You can also refer to the documentation for the original ``turbogears.feed``
107 package on the TurboGears documentation wiki:
108
109 http://docs.turbogears.org/1.0/FeedController
110
111 All information on this page is also still valid for TurboFeeds, you
112 just have to replace::
113
114 from turbogears.feed import FeedController
115
116 with::
117
118 from turbofeeds import FeedController
119
120 Credits
121 -------
122
123 * The ``turbogears.feed`` package was first introduced in TurboGears version
124 0.9a1 and was added by Elvelind Grandin.
125
126 * Christopher Arndt turned it into the TurboGears extension TurboFeeds.
127
128 * Other contributors include:
129
130 Florent Aide, Simon Belak, Kevin Dangoor, Charles Duffy, Alberto Valverde,
131 Jorge Vargas
132
133 Please notify the maintainer, if you think your name should belong here too.
134
135 * The feed icons used by the CSS for the FeedLinks widget where taken from
136 http://www.feedicons.com/.
137
138
139 .. _turbogears: http://www.turbogears.org/
140 .. _cheeseshop: http://cheeseshop.python.org/pypi/TurboFeeds
141 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
142 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
143 .. _ez_setup.py: http://peak.telecommunity.com/dist/ez_setup.py
144 .. _api documentation: http://chrisarndt.de/projects/turbofeeds/api/index.html
145 .. _subversion repository:
146 http://svn.turbogears.org/projects/TurboFeeds/trunk#egg=turbofeeds-dev
147
148 """
149 __docformat__ = 'restructuredtext'
150
151 name = "TurboFeeds"
152 version = "0.2b"
153 date = "$Date: 2009-09-27 05:36:36 +0200 (Sun, 27. Sep 2009) $"
154
155 _doclines = __doc__.split('\n')
156 description = _doclines[0]
157 long_description = '\n'.join(_doclines[2:])
158 author = "Elvelind Grandin, Christopher Arndt"
159 author_email = "chris@chrisarndt.de"
160 maintainer = "Christopher Arndt"
161 maintainer_email = "chris@chrisarndt.de"
162 copyright = "(c) 2006 - 2009 Elvelind Grandin et al."
163 license = "MIT license"
164
165 url = "http://chrisarndt.de/projects/turbofeeds"
166 download_url = "http://cheeseshop.python.org/pypi/TurboFeeds"
167