13 # FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more |
13 # FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more |
14 # details. |
14 # details. |
15 # |
15 # |
16 # You should have received a copy of the GNU Lesser General Public License along |
16 # You should have received a copy of the GNU Lesser General Public License along |
17 # with CubicWeb. If not, see <http://www.gnu.org/licenses/>. |
17 # with CubicWeb. If not, see <http://www.gnu.org/licenses/>. |
18 """ |
18 """Standard interfaces. Deprecated in favor of adapters. |
19 Standard interfaces. |
|
20 |
19 |
21 .. note:: |
20 .. note:: |
22 |
21 |
23 The `implements` selector matches not only entity classes but also |
22 The `implements` selector used to match not only entity classes but also their |
24 their interfaces. Writing __select__ = implements('IGeocodable') is |
23 interfaces. This will disappear in a future version. You should define an |
25 a perfectly fine thing to do. |
24 adapter for that interface and use `adaptable('MyIFace')` selector on appobjects |
|
25 that require that interface. |
|
26 |
26 """ |
27 """ |
27 __docformat__ = "restructuredtext en" |
28 __docformat__ = "restructuredtext en" |
28 |
29 |
29 from logilab.common.interface import Interface |
30 from logilab.common.interface import Interface |
30 |
31 |
31 class IEmailable(Interface): |
32 |
32 """interface for emailable entities""" |
33 # XXX deprecates in favor of IProgressAdapter |
33 |
|
34 def get_email(self): |
|
35 """return email address""" |
|
36 |
|
37 @classmethod |
|
38 def allowed_massmail_keys(cls): |
|
39 """returns a set of allowed email substitution keys |
|
40 |
|
41 The default is to return the entity's attribute list but an |
|
42 entity class might override this method to allow extra keys. |
|
43 For instance, the Person class might want to return a `companyname` |
|
44 key. |
|
45 """ |
|
46 |
|
47 def as_email_context(self): |
|
48 """returns the dictionary as used by the sendmail controller to |
|
49 build email bodies. |
|
50 |
|
51 NOTE: the dictionary keys should match the list returned by the |
|
52 `allowed_massmail_keys` method. |
|
53 """ |
|
54 |
|
55 |
|
56 class IWorkflowable(Interface): |
|
57 """interface for entities dealing with a specific workflow""" |
|
58 # XXX to be completed, see cw.entities.wfobjs.WorkflowableMixIn |
|
59 |
|
60 @property |
|
61 def state(self): |
|
62 """return current state name""" |
|
63 |
|
64 def change_state(self, stateeid, trcomment=None, trcommentformat=None): |
|
65 """change the entity's state to the state of the given name in entity's |
|
66 workflow |
|
67 """ |
|
68 |
|
69 def latest_trinfo(self): |
|
70 """return the latest transition information for this entity |
|
71 """ |
|
72 |
|
73 |
|
74 class IProgress(Interface): |
34 class IProgress(Interface): |
75 """something that has a cost, a state and a progression |
35 """something that has a cost, a state and a progression""" |
76 |
|
77 Take a look at cubicweb.mixins.ProgressMixIn for some |
|
78 default implementations |
|
79 """ |
|
80 |
36 |
81 @property |
37 @property |
82 def cost(self): |
38 def cost(self): |
83 """the total cost""" |
39 """the total cost""" |
84 |
40 |
133 """returns date on which the subtask has been completed""" |
89 """returns date on which the subtask has been completed""" |
134 |
90 |
135 def contractors(self): |
91 def contractors(self): |
136 """returns the list of persons supposed to work on this task""" |
92 """returns the list of persons supposed to work on this task""" |
137 |
93 |
138 |
94 # XXX deprecates in favor of IEmbedableAdapter |
139 class ITree(Interface): |
95 class IEmbedable(Interface): |
140 |
96 """interface for embedable entities""" |
141 def parent(self): |
97 |
142 """returns the parent entity""" |
98 def embeded_url(self): |
143 |
99 """embed action interface""" |
144 def children(self): |
100 |
145 """returns the item's children""" |
101 # XXX deprecates in favor of ICalendarAdapter |
146 |
102 class ICalendarViews(Interface): |
147 def children_rql(self): |
103 """calendar views interface""" |
148 """XXX returns RQL to get children""" |
104 def matching_dates(self, begin, end): |
149 |
105 """ |
150 def iterchildren(self): |
106 :param begin: day considered as begin of the range (`DateTime`) |
151 """iterates over the item's children""" |
107 :param end: day considered as end of the range (`DateTime`) |
152 |
108 |
153 def is_leaf(self): |
109 :return: |
154 """returns true if this node as no child""" |
110 a list of dates (`DateTime`) in the range [`begin`, `end`] on which |
155 |
111 this entity apply |
156 def is_root(self): |
112 """ |
157 """returns true if this node has no parent""" |
113 |
158 |
114 # XXX deprecates in favor of ICalendarableAdapter |
159 def root(self): |
115 class ICalendarable(Interface): |
160 """returns the root object""" |
116 """interface for items that do have a begin date 'start' and an end date 'stop' |
161 |
|
162 |
|
163 ## web specific interfaces #################################################### |
|
164 |
|
165 |
|
166 class IPrevNext(Interface): |
|
167 """interface for entities which can be linked to a previous and/or next |
|
168 entity |
|
169 """ |
117 """ |
170 |
118 |
171 def next_entity(self): |
119 @property |
172 """return the 'next' entity""" |
120 def start(self): |
173 def previous_entity(self): |
121 """return start date""" |
174 """return the 'previous' entity""" |
122 |
175 |
123 @property |
176 |
124 def stop(self): |
177 class IBreadCrumbs(Interface): |
125 """return stop state""" |
178 """interface for entities which can be "located" on some path""" |
126 |
179 |
127 # XXX deprecates in favor of ICalendarableAdapter |
180 # XXX fix recurs ! |
128 class ITimetableViews(Interface): |
181 def breadcrumbs(self, view, recurs=False): |
129 """timetable views interface""" |
182 """return a list containing some: |
130 def timetable_date(self): |
183 |
131 """XXX explain |
184 * tuple (url, label) |
132 |
185 * entity |
133 :return: date (`DateTime`) |
186 * simple label string |
134 """ |
187 |
135 |
188 defining path from a root to the current view |
136 # XXX deprecates in favor of IGeocodableAdapter |
189 |
137 class IGeocodable(Interface): |
190 the main view is given as argument so breadcrumbs may vary according |
138 """interface required by geocoding views such as gmap-view""" |
191 to displayed view (may be None). When recursing on a parent entity, |
139 |
192 the `recurs` argument should be set to True. |
140 @property |
193 """ |
141 def latitude(self): |
194 |
142 """returns the latitude of the entity""" |
195 |
143 |
|
144 @property |
|
145 def longitude(self): |
|
146 """returns the longitude of the entity""" |
|
147 |
|
148 def marker_icon(self): |
|
149 """returns the icon that should be used as the marker""" |
|
150 |
|
151 # XXX deprecates in favor of ISIOCItemAdapter |
|
152 class ISiocItem(Interface): |
|
153 """interface for entities which may be represented as an ISIOC item""" |
|
154 |
|
155 def isioc_content(self): |
|
156 """return item's content""" |
|
157 |
|
158 def isioc_container(self): |
|
159 """return container entity""" |
|
160 |
|
161 def isioc_type(self): |
|
162 """return container type (post, BlogPost, MailMessage)""" |
|
163 |
|
164 def isioc_replies(self): |
|
165 """return replies items""" |
|
166 |
|
167 def isioc_topics(self): |
|
168 """return topics items""" |
|
169 |
|
170 # XXX deprecates in favor of ISIOCContainerAdapter |
|
171 class ISiocContainer(Interface): |
|
172 """interface for entities which may be represented as an ISIOC container""" |
|
173 |
|
174 def isioc_type(self): |
|
175 """return container type (forum, Weblog, MailingList)""" |
|
176 |
|
177 def isioc_items(self): |
|
178 """return contained items""" |
|
179 |
|
180 # XXX deprecates in favor of IEmailableAdapter |
|
181 class IFeed(Interface): |
|
182 """interface for entities with rss flux""" |
|
183 |
|
184 def rss_feed_url(self): |
|
185 """""" |
|
186 |
|
187 # XXX deprecates in favor of IDownloadableAdapter |
196 class IDownloadable(Interface): |
188 class IDownloadable(Interface): |
197 """interface for downloadable entities""" |
189 """interface for downloadable entities""" |
198 |
190 |
199 def download_url(self): # XXX not really part of this interface |
191 def download_url(self): # XXX not really part of this interface |
200 """return an url to download entity's content""" |
192 """return an url to download entity's content""" |
205 def download_file_name(self): |
197 def download_file_name(self): |
206 """return file name of the downloadable content""" |
198 """return file name of the downloadable content""" |
207 def download_data(self): |
199 def download_data(self): |
208 """return actual data of the downloadable content""" |
200 """return actual data of the downloadable content""" |
209 |
201 |
210 |
202 # XXX deprecates in favor of IPrevNextAdapter |
211 class IEmbedable(Interface): |
203 class IPrevNext(Interface): |
212 """interface for embedable entities""" |
204 """interface for entities which can be linked to a previous and/or next |
213 |
205 entity |
214 def embeded_url(self): |
|
215 """embed action interface""" |
|
216 |
|
217 class ICalendarable(Interface): |
|
218 """interface for items that do have a begin date 'start' and an end date 'stop' |
|
219 """ |
206 """ |
220 |
207 |
221 @property |
208 def next_entity(self): |
222 def start(self): |
209 """return the 'next' entity""" |
223 """return start date""" |
210 def previous_entity(self): |
224 |
211 """return the 'previous' entity""" |
225 @property |
212 |
226 def stop(self): |
213 # XXX deprecates in favor of IBreadCrumbsAdapter |
227 """return stop state""" |
214 class IBreadCrumbs(Interface): |
228 |
215 |
229 class ICalendarViews(Interface): |
216 def breadcrumbs(self, view, recurs=False): |
230 """calendar views interface""" |
217 pass |
231 def matching_dates(self, begin, end): |
218 |
232 """ |
219 # XXX deprecates in favor of ITreeAdapter |
233 :param begin: day considered as begin of the range (`DateTime`) |
220 class ITree(Interface): |
234 :param end: day considered as end of the range (`DateTime`) |
221 |
235 |
222 def parent(self): |
236 :return: |
223 """returns the parent entity""" |
237 a list of dates (`DateTime`) in the range [`begin`, `end`] on which |
224 |
238 this entity apply |
225 def children(self): |
239 """ |
226 """returns the item's children""" |
240 |
227 |
241 class ITimetableViews(Interface): |
228 def children_rql(self): |
242 """timetable views interface""" |
229 """XXX returns RQL to get children""" |
243 def timetable_date(self): |
230 |
244 """XXX explain |
231 def iterchildren(self): |
245 |
232 """iterates over the item's children""" |
246 :return: date (`DateTime`) |
233 |
247 """ |
234 def is_leaf(self): |
248 |
235 """returns true if this node as no child""" |
249 class IGeocodable(Interface): |
236 |
250 """interface required by geocoding views such as gmap-view""" |
237 def is_root(self): |
251 |
238 """returns true if this node has no parent""" |
252 @property |
239 |
253 def latitude(self): |
240 def root(self): |
254 """returns the latitude of the entity""" |
241 """returns the root object""" |
255 |
242 |
256 @property |
|
257 def longitude(self): |
|
258 """returns the longitude of the entity""" |
|
259 |
|
260 def marker_icon(self): |
|
261 """returns the icon that should be used as the marker |
|
262 (returns None for default) |
|
263 """ |
|
264 |
|
265 class IFeed(Interface): |
|
266 """interface for entities with rss flux""" |
|
267 |
|
268 def rss_feed_url(self): |
|
269 """return an url which layout sub-entities item |
|
270 """ |
|
271 |
|
272 class ISiocItem(Interface): |
|
273 """interface for entities (which are item |
|
274 in sioc specification) with sioc views""" |
|
275 |
|
276 def isioc_content(self): |
|
277 """return content entity""" |
|
278 |
|
279 def isioc_container(self): |
|
280 """return container entity""" |
|
281 |
|
282 def isioc_type(self): |
|
283 """return container type (post, BlogPost, MailMessage)""" |
|
284 |
|
285 def isioc_replies(self): |
|
286 """return replies items""" |
|
287 |
|
288 def isioc_topics(self): |
|
289 """return topics items""" |
|
290 |
|
291 class ISiocContainer(Interface): |
|
292 """interface for entities (which are container |
|
293 in sioc specification) with sioc views""" |
|
294 |
|
295 def isioc_type(self): |
|
296 """return container type (forum, Weblog, MailingList)""" |
|
297 |
|
298 def isioc_items(self): |
|
299 """return contained items""" |
|