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