cubicweb: comparison web/views/primary.py

equal deleted inserted replaced

-:287813c487b7
+:2172978be237
 # FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
 # details.
 #
 # You should have received a copy of the GNU Lesser General Public License along
 # with CubicWeb.  If not, see <http://www.gnu.org/licenses/>.
-"""The default primary view"""
+"""
+Public API of the PrimaryView class
+````````````````````````````````````
+.. autoclass:: cubicweb.web.views.primary.PrimaryView
+Views that may be used to display an entity's attribute or relation
+```````````````````````````````````````````````````````````````````
+Yoy may easily the display of an attribute or relation by simply configuring the
+view using one of `primaryview_display_ctrl` or `reledit_ctrl` to use one of the
+views describled below. For instance:
+.. sourcecode:: python
+primaryview_display_ctrl.tag_attribute(('Foo', 'bar'), {'vid': 'attribute'})
+.. autoclass:: AttributeView
+.. autoclass:: URLAttributeView
+"""
 __docformat__ = "restructuredtext en"
 _ = unicode
 from warnings import warn
 from cubicweb.schema import META_RTYPES, VIRTUAL_RTYPES, display_name
 from cubicweb.web import uicfg, component
 class PrimaryView(EntityView):
-"""the full view of an non final entity"""
+"""
+The basic layout of a primary view is as in the :ref:`primary_view_layout`
+section. This layout is actually drawn by the `render_entity` method.
+The methods you may want to modify while customizing a ``PrimaryView``
+are:
+.. automethod:: cubicweb.web.views.primary.PrimaryView.render_entity_title
+.. automethod:: cubicweb.web.views.primary.PrimaryView.render_entity_attributes
+.. automethod:: cubicweb.web.views.primary.PrimaryView.render_entity_relations
+.. automethod:: cubicweb.web.views.primary.PrimaryView.render_side_boxes
+The placement of relations in the relations section or in side boxes
+can be controlled through the :ref:`primary_view_configuration` mechanism.
+.. automethod:: cubicweb.web.views.primary.PrimaryView.content_navigation_components
+Also, please note that by setting the following attributes in your
+subclass, you can already customize some of the rendering:
+:attr:`show_attr_label`
+Renders the attribute label next to the attribute value if set to `True`.
+Otherwise, does only display the attribute value.
+:attr:`show_rel_label`
+Renders the relation label next to the relation value if set to `True`.
+Otherwise, does only display the relation value.
+:attr:`skip_none`
+Does not render an attribute value that is None if set to `True`.
+:attr:`main_related_section`
+Renders the relations of the entity if set to `True`.
+A good practice is for you to identify the content of your entity type for
+which the default rendering does not answer your need so that you can focus
+on the specific method (from the list above) that needs to be modified. We
+do not advise you to overwrite ``render_entity`` unless you want a
+completely different layout.
+"""
 __regid__ = 'primary'
 title = _('primary')
 show_attr_label = True
 show_rel_label = True
 skip_none = True
 self.render_side_boxes(boxes)
 self.w(u'</div>')
 self.w(u'</td></tr></table>')
 def content_navigation_components(self, context):
+"""This method is applicable only for entity type implementing the
+interface `IPrevNext`. This interface is for entities which can be
+linked to a previous and/or next entity. This method will render the
+navigation links between entities of this type, either at the top or at
+the bottom of the page given the context (navcontent{top|bottom}).
+"""
 self.w(u'<div class="%s">' % context)
 for comp in self._cw.vreg['ctxcomponents'].poss_visible_objects(
 self._cw, rset=self.cw_rset, view=self, context=context):
 # XXX bw compat code
 try:
 except TypeError:
 comp.render(w=self.w)
 self.w(u'</div>')
 def render_entity_title(self, entity):
-"""default implementation return dc_title"""
+"""Renders the entity title, by default using entity's
+:meth:`dc_title()` method.
+"""
 title = xml_escape(entity.dc_title())
 if title:
 if self.is_primary():
 self.w(u'<h1>%s</h1>' % title)
 else:
 def summary(self, entity):
 """default implementation return an empty string"""
 return u''
 def render_entity_attributes(self, entity):
+"""Renders all attributes and relations in the 'attributes' section. The
+:attr:`skip_none` attribute controls the display of `None` valued
+attributes.
+"""
 display_attributes = []
 for rschema, _, role, dispctrl in self._section_def(entity, 'attributes'):
 vid = dispctrl.get('vid', 'reledit')
 if rschema.final or vid == 'reledit' or dispctrl.get('rtypevid'):
 value = entity.view(vid, rtype=rschema.type, role=role,
 def render_attribute(self, label, value, table=False):
 self.field(label, value, tr=False, table=table)
 def render_entity_relations(self, entity):
+"""Renders all relations in the 'relations' section."""
 for rschema, tschemas, role, dispctrl in self._section_def(entity, 'relations'):
 if rschema.final or dispctrl.get('rtypevid'):
 vid = dispctrl.get('vid', 'reledit')
 try:
 rview = self._cw.vreg['views'].select(
 self.w(u'<h4>%s</h4>' % label)
 self.w(value)
 self.w(u'</div>')
 def render_side_boxes(self, boxes):
-"""display side related relations:
+"""Renders side boxes on the right side of the content. This will
-non-meta in a first step, meta in a second step
+generate a box for each relation in the 'sidebox' section, as well as
+explicit box appobjects selectable in this context.
 """
 for box in boxes:
 if isinstance(box, tuple):
 try:
 label, rset, vid, dispctrl  = box
 """Display a rset, usually containing entities linked to another entity
 being displayed.
 It will try to display nicely according to the number of items in the result
 set.
+XXX include me in the doc
 """
 __regid__ = 'autolimited'
 def call(self, **kwargs):
 if 'dispctrl' in self.cw_extra_kwargs:
 self._cw._('see them all')))
 self.w(u'</div>')
 class URLAttributeView(EntityView):
-"""use this view for attributes whose value is an url and that you want
+""":__regid__: *urlattr*
-to display as clickable link
+This view will wrap an attribute value (hence expect a string) into an '<a>'
+HTML tag to display a clickable link.
 """
 __regid__ = 'urlattr'
 __select__ = EntityView.__select__ & match_kwargs('rtype')
-def cell_call(self, row, col, rtype, **kwargs):
+def entity_call(self, entity, rtype, **kwargs):
-entity = self.cw_rset.get_entity(row, col)
 url = entity.printable_value(rtype)
 if url:
 self.w(u'<a href="%s">%s</a>' % (url, url))
 class AttributeView(EntityView):
-"""use this view on an entity as an alternative to more sophisticated
+""":__regid__: *attribute*
-views such as reledit.
+This view is generally used to disable the *reledit* feature. It works on
-Ex. usage:
+both relations and attributes.
-uicfg.primaryview_display_ctrl.tag_attribute(('Foo', 'bar'), {'vid': 'attribute'})
 """
 __regid__ = 'attribute'
 __select__ = EntityView.__select__ & match_kwargs('rtype')
-def cell_call(self, row, col, rtype, role, **kwargs):
+def entity_call(self, entity, rtype, **kwargs):
-entity = self.cw_rset.get_entity(row, col)
 if self._cw.vreg.schema.rschema(rtype).final:
 self.w(entity.printable_value(rtype))
 else:
 dispctrl = uicfg.primaryview_display_ctrl.etype_get(
 entity.e_schema, rtype, role, '*')
 self.wview('autolimited', rset, initargs={'dispctrl': dispctrl})
 class ToolbarLayout(component.Layout):
+# XXX include me in the doc
 __select__ = match_context('ctxtoolbar')
 def render(self, w):
 if self.init_rendering():
 self.cw_extra_kwargs['view'].render_body(w)
 ## default primary ui configuration ###########################################
 _pvs = uicfg.primaryview_section
 for rtype in META_RTYPES:

changeset 7845	2172978be237
parent 7797	a71618a75b53
parent 7844	0208c65a88a5
child 7846	dd3f0871d8b7