1 #!/usr/bin/python2.5 |
|
2 # |
|
3 # Copyright 2008 the Melange authors. |
|
4 # |
|
5 # Licensed under the Apache License, Version 2.0 (the "License"); |
|
6 # you may not use this file except in compliance with the License. |
|
7 # You may obtain a copy of the License at |
|
8 # |
|
9 # http://www.apache.org/licenses/LICENSE-2.0 |
|
10 # |
|
11 # Unless required by applicable law or agreed to in writing, software |
|
12 # distributed under the License is distributed on an "AS IS" BASIS, |
|
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
14 # See the License for the specific language governing permissions and |
|
15 # limitations under the License. |
|
16 |
|
17 """Helpers for displaying arbitrarily nested menus as HTML lists. |
|
18 """ |
|
19 |
|
20 __authors__ = [ |
|
21 '"Todd Larsen" <tlarsen@google.com>', |
|
22 ] |
|
23 |
|
24 |
|
25 from soc.logic import menu |
|
26 |
|
27 |
|
28 class HtmlMenu: |
|
29 """Ordered collection of MenuItem objects as <p>...</p> paragraphs. |
|
30 """ |
|
31 ITEM_PREFIX_FMT = '%(indent)s<p>' |
|
32 ITEM_SUFFIX_FMT = '%(indent)s</p>' |
|
33 |
|
34 def __init__(self, menu, item_class=None): |
|
35 """Wraps an soc.logic.menu.Menu in order to render it as HTML. |
|
36 |
|
37 Args: |
|
38 menu: an soc.logic.menu.Menu object |
|
39 item_class: style used to render the MenuItems contained in menu; |
|
40 default is None, which causes AHrefMenuItem to be used |
|
41 """ |
|
42 self._menu = menu |
|
43 |
|
44 # workaround for circular dependency between AHrefMenuItem and this class |
|
45 if not item_class: |
|
46 item_class = AHrefMenuItem |
|
47 |
|
48 self._item_class = item_class |
|
49 |
|
50 def getHtmlTags(self, indent): |
|
51 """Returns list of HTML tags for arbitrarily nested items in the menu. |
|
52 |
|
53 Args: |
|
54 indent: string prepended to the beginning of each line of output |
|
55 (usually consists entirely of spaces) |
|
56 |
|
57 Returns: |
|
58 a list of strings that can be joined with '\n' into a single string |
|
59 to produce an entire <ul>...</ul> list in HTML |
|
60 """ |
|
61 tags = [] |
|
62 |
|
63 if self._menu.items: |
|
64 tags.append(self.ITEM_PREFIX_FMT % {'indent': indent}) |
|
65 |
|
66 for item in self._menu.items: |
|
67 tags.extend(self._item_class( |
|
68 item, menu_class=self.__class__).getHtmlTags(indent + ' ')) |
|
69 |
|
70 tags.append(self.ITEM_SUFFIX_FMT % {'indent': indent}) |
|
71 |
|
72 return tags |
|
73 |
|
74 def __str__(self): |
|
75 return '\n'.join(self.getHtmlTags('')) |
|
76 |
|
77 |
|
78 class UlMenu(HtmlMenu): |
|
79 """Ordered collection of MenuItem objects as a <ul> list. |
|
80 """ |
|
81 ITEM_PREFIX_FMT = '%(indent)s<ul>' |
|
82 ITEM_SUFFIX_FMT = '%(indent)s</ul>' |
|
83 |
|
84 def __init__(self, menu, item_class=None): |
|
85 """Wraps an soc.logic.menu.Menu in order to render it as HTML. |
|
86 |
|
87 Args: |
|
88 menu: an soc.logic.menu.Menu object |
|
89 item_class: style used to render the MenuItems contained in menu; |
|
90 default is None, which causes LiMenuItem to be used |
|
91 """ |
|
92 # workaround for circular dependency between LiMenuItem and this class |
|
93 if not item_class: |
|
94 item_class = LiMenuItem |
|
95 |
|
96 HtmlMenu.__init__(self, menu, item_class=item_class) |
|
97 |
|
98 |
|
99 class HtmlMenuItem: |
|
100 """Base class for specific MenuItem wrappers used by HtmlMenu sub-classes. |
|
101 """ |
|
102 |
|
103 def __init__(self, item, menu_class=HtmlMenu): |
|
104 """Wraps an soc.logic.menu.MenuItem in order to render it as HTML. |
|
105 |
|
106 Args: |
|
107 item: an soc.logic.menu.MenuItem object to wrap, in order to produce |
|
108 a representation of it as HTML tags later |
|
109 menu_class: a class derived from HtmlMenu, used to style any sub-menu |
|
110 of the MenuItem; default is HtmlMenu |
|
111 """ |
|
112 self._item = self.escapeItem(item) |
|
113 self._menu_class = menu_class |
|
114 |
|
115 def getItemHtmlTags(self, indent): |
|
116 """Returns list of HTML tags for the menu item itself. |
|
117 |
|
118 This method is intended to be overridden by sub-classes. |
|
119 |
|
120 Args: |
|
121 indent: string prepended to the beginning of each line of output |
|
122 (usually consists entirely of spaces) |
|
123 |
|
124 Returns: |
|
125 a list of strings that can be joined with '\n' into a single string |
|
126 to produce: |
|
127 <b>name</b> value <i>(annotation)</i> |
|
128 with value and/or <i>(annotation)</i> omitted if either is missing |
|
129 """ |
|
130 # TODO(tlarsen): implement "selected" style |
|
131 |
|
132 tags = ['%s<b>%s</b>' % (indent, self._item.name)] |
|
133 |
|
134 if self._item.value: |
|
135 tags.append('%s%s' % (indent, self._item.value)) |
|
136 |
|
137 if self._item.annotation: |
|
138 tags.append('%s<i>(%s)</i>' % (indent, self._item.annotation)) |
|
139 |
|
140 return tags |
|
141 |
|
142 def getSubMenuHtmlTags(self, indent): |
|
143 """Returns list of HTML tags for any sub-menu, if one exists. |
|
144 |
|
145 Args: |
|
146 indent: string prepended to the beginning of each line of output |
|
147 (usually consists entirely of spaces) |
|
148 |
|
149 Returns: |
|
150 an empty list if there is no sub-menu |
|
151 -OR- |
|
152 the list of HTML tags that render the entire sub-menu (depends on the |
|
153 menu_class that was provided to __init__() |
|
154 """ |
|
155 if not self._item.sub_menu: |
|
156 return [] |
|
157 |
|
158 return self._menu_class(self._item.sub_menu, |
|
159 item_class=self.__class__).getHtmlTags(indent) |
|
160 |
|
161 def getHtmlTags(self, indent): |
|
162 """Returns list of HTML tags for a menu item (and possibly its sub-menus). |
|
163 |
|
164 Args: |
|
165 indent: string prepended to the beginning of each line of output |
|
166 (usually consists entirely of spaces) |
|
167 |
|
168 Returns: |
|
169 a list of strings that can be joined with '\n' into a single string |
|
170 to produce an HTML representation of the wrapped MenuItem, with |
|
171 arbitrarily nested sub-menus possibly appended |
|
172 """ |
|
173 return self.getItemHtmlTags(indent) + self.getSubMenuHtmlTags(indent) |
|
174 |
|
175 def escapeItem(self, item): |
|
176 """HTML-escapes possibly user-supplied fields to prevent XSS. |
|
177 |
|
178 Args: |
|
179 item: an soc.logic.menu.MenuItem that is altered in-place; the |
|
180 fields that are potentially user-provided (name, value, annotation) |
|
181 are escaped using self.escapeText() |
|
182 |
|
183 Returns: |
|
184 the originally supplied item, for convenience, so that this method can |
|
185 be combined with an assignment |
|
186 """ |
|
187 item.name = self.escapeText(item.name) |
|
188 item.value = self.escapeText(item.value) |
|
189 item.annotation = self.escapeText(item.annotation) |
|
190 return item |
|
191 |
|
192 def escapeText(self, text): |
|
193 """ |
|
194 """ |
|
195 # TODO(tlarsen): user-supplied content *must* be escaped to prevent XSS |
|
196 return text |
|
197 |
|
198 def __str__(self): |
|
199 return '\n'.join(self.getHtmlTags('')) |
|
200 |
|
201 |
|
202 class AHrefMenuItem(HtmlMenuItem): |
|
203 """Provides HTML menu item properties as attributes as an <a href> link. |
|
204 """ |
|
205 |
|
206 def getItemHtmlTags(self, indent): |
|
207 """Returns list of HTML tags for the menu item itself. |
|
208 |
|
209 Args: |
|
210 indent: string prepended to the beginning of each line of output |
|
211 (usually consists entirely of spaces) |
|
212 |
|
213 Returns: |
|
214 a list of strings that can be joined with '\n' into a single string |
|
215 to produce an <a href="...">...</a> link, or just the MenuItem.name |
|
216 as plain text if there was no AHrefMenuItem.value URL |
|
217 """ |
|
218 # TODO(tlarsen): implement "selected" style |
|
219 |
|
220 if not self._item.value: |
|
221 # if no URL, then not a link, so just display item.name as text |
|
222 return [self._item.name] |
|
223 |
|
224 # URL supplied, so make an <a href="item.value">item.name</a> link |
|
225 return ['%s<a href=' % indent, |
|
226 '%s "%s"' % (indent, self._item.value), |
|
227 '%s>%s</a>' % (indent, self._item.name)] |
|
228 |
|
229 |
|
230 class LiMenuItem(AHrefMenuItem): |
|
231 """Provides HTML menu item properties as attributes as an <li> list item. |
|
232 """ |
|
233 |
|
234 def __init__(self, item, menu_class=UlMenu): |
|
235 """Wraps an soc.logic.menu.MenuItem in order to render it as HTML. |
|
236 |
|
237 Args: |
|
238 item: an soc.logic.menu.MenuItem object to wrap, in order to produce |
|
239 a representation of it as HTML tags later |
|
240 menu_class: a class derived from HtmlMenu, used to style any sub-menu |
|
241 of the MenuItem; default is UlMenu |
|
242 """ |
|
243 AHrefMenuItem.__init__(self, item, menu_class=menu_class) |
|
244 |
|
245 def getHtmlTags(self, indent): |
|
246 """Returns <a href> link wrapped as an <li> list item. |
|
247 |
|
248 See also AHrefMenuItem.getHtmlTags(). |
|
249 """ |
|
250 return (['%s<li>' % indent] |
|
251 + AHrefMenuItem.getHtmlTags(self, indent + ' ') |
|
252 + ['%s</li>' % indent]) |
|