1
2
3 """TurboGears extension providing enhanced flash message display functions.
4
5 This package provides an enhanced version of the ``turbogears.flash()``
6 function, giving your users much nicer-looking message boxes that can change
7 their appearance based on the status of the message. With JavaScript enabled,
8 messages can fade out after a timeout or be dismissed by the user with a
9 mouse-click.
10
11 This is accomplished by encoding the message with JSON and decoding it again in
12 the template of the target page. This is handled completely automatic and the
13 programmer can just use the functional interface, e.g.
14 ``fancyflash.error("Duh!")``.
15
16 Additionally, you can display messages with a simple JavaScript function call, for example when processing the results of an AJAX call in your callback function for ``loadJSONDoc``.
17
18 For more information see the source of the ``fancyflash`` package, the
19 epydoc-generated `API documentation`_ and the FancyFlashExample_ application.
20
21
22 Installation
23 ------------
24
25 To install TurboFancyFlash from the Cheeseshop_ use `easy_install`_::
26
27 [sudo] easy_install TurboFancyFlash
28
29 This requires the setuptools_ package to be installed. If you have not done so
30 already, download the `ez_setup.py`_ script and run it to install setuptools.
31
32
33 Usage
34 -----
35
36 Controller (``controllers.py``)::
37
38 # Import TurboGears
39 from turbogears import controllers, expose, redirect, validate, validators
40
41 # Import fancyflash package
42 import fancyflash as ff
43
44 # Set the default timeout for message box display
45 ff.set_default_flash_timeout(5)
46
47 # Let FancyFlashWidget be included on every page
48 ff.register_flash_widget()
49
50 class FlashTestController(controllers.Controller):
51
52 @expose('templates.welcome')
53 def index(self, timeout=0):
54 return {}
55
56 @expose()
57 def info(self):
58 ff.info("Hello TurboGears!")
59 redirect('/')
60
61 @expose()
62 @validate(validators=dict(timeout=validators.Int))
63 def success(self, timeout=0, tg_errors=None):
64 ff.success("Hello TurboGears!", timeout)
65 redirect('/')
66
67 @expose()
68 @validate(validators=dict(status=validators.String))
69 def message(self, status="info", tg_errors=None):
70 ff.statusmessage("Hello TurboGears!", status)
71 redirect('/')
72
73 Master template (``master.kid``)::
74
75 <div id="main_content">
76 <div py:replace="tg_fancyflashwidget(tg_flash)">Status message
77 appears here</div>
78
79 <div py:replace="[item.text]+item[:]"/>
80
81 ...
82 </div>
83
84
85 Acknowledgments
86 ---------------
87
88 The idea for this widget is based on a `blog post`_ by Lee McFadden:
89
90 .. _blog post:
91 http://www.splee.co.uk/2005/11/23/fancy-status-messages-using-tg_flash/
92
93
94 Todo
95 ----
96
97 * Test in IE
98 * Test opacity in Safari
99
100 If I have time:
101
102 * Add argument for dialog position (implement by writing CSS dynamically).
103 * Round boxes for non-Gecko browsers
104 * Add AJAX widget, which displays result of ``loadJSONDoc`` as fancy status
105 message.
106
107 .. _api documentation:
108 http://chrisarndt.de/projects/fancyflash/api/index.html
109 .. _fancyflashexample: http://chrisarndt.de/projects/fancyflashexample/
110 .. _cheeseshop: http://cheeseshop.python.org/pypi/TurboFancyFlash
111 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
112 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
113 .. _ez_setup.py: http://peak.telecommunity.com/dist/ez_setup.py
114 """
115 __docformat__ = 'restructuredtext'
116
117 name = "TurboFancyFlash"
118 version = "0.1a"
119 date = "$Date: 2008-02-04 18:13:04 +0100 (Mo, 04 Feb 2008) $"
120
121 _doclines = __doc__.split('\n')
122 description = _doclines[0]
123 long_description = '\n'.join(_doclines[2:])
124
125 author = "Christopher Arndt"
126 author_email = "chris@chrisarndt.de"
127 copyright = "(c) 2006-2008 Christopher Arndt"
128 license = "MIT license"
129
130 url = "http://chrisarndt.de/projects/fancyflash/"
131 download_url = "http://cheeseshop.python.org/pypi/%s" % version
132