#:organization: Logilab

#:copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

#:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr

#:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

"""This module (``cubicweb.web.uicfg``) regroups a set of structures that may be used to configure

various options of the generated web interface.

To configure the interface generation, we use ``RelationTag`` objects.

Primary view configuration

``````````````````````````

XXX section moved to the doc, is maintained there

If you want to customize the primary view of an entity, overriding the primary

view class may not be necessary. For simple adjustments (attributes or relations

display locations and styles), a much simpler way is to use uicfg.

Attributes/relations display location

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the primary view, there are 3 sections where attributes and relations can be

displayed (represented in pink in the image below):

* attributes

* relations

* sideboxes

.. image:: ../../images/primaryview_template.png

**Attributes** can only be displayed in the attributes section (default

  behavior). They can also be hidden.

For instance, to hide the ``title`` attribute of the ``Blog`` entity:

.. sourcecode:: python

   from cubicweb.web import uicfg

   uicfg.primaryview_section.tag_attribute(('Blog', 'title'), 'hidden')

**Relations** can be either displayed in one of the three sections or hidden.

For relations, there are two methods:

* ``tag_object_of`` for modifying the primary view of the object

* ``tag_subject_of`` for modifying the primary view of the subject

These two methods take two arguments:

* a triplet ``(subject, relation_name, object)``, where subject or object can be replaced with ``'*'``

* the section name or ``hidden``

.. sourcecode:: python

   # hide every relation ``entry_of`` in the ``Blog`` primary view

   uicfg.primaryview_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden')

   # display ``entry_of`` relations in the ``relations`` section in the ``BlogEntry`` primary view

   uicfg.primaryview_section.tag_subject_of(('BlogEntry', 'entry_of', '*'),

                                             'relations')

Display content

^^^^^^^^^^^^^^^

You can use ``primaryview_display_ctrl`` to customize the display of attributes

or relations. Values of ``primaryview_display_ctrl`` are dictionaries.

Common keys for attributes and relations are:

* ``vid``: specifies the regid of the view for displaying the attribute or the relation.

  If ``vid`` is not specified, the default value depends on the section:

  * ``attributes`` section: 'reledit' view

  * ``relations`` section: 'autolimited' view

  * ``sideboxes`` section: 'sidebox' view

* ``order``: int used to control order within a section. When not specified,

  automatically set according to order in which tags are added.

Keys for relations only:

* ``label``: label for the relations section or side box

* ``showlabel``: boolean telling whether the label is displayed

* ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed

* ``filter``: callback taking the related result set as argument and returning it filtered

.. sourcecode:: python

   # in ``CWUser`` primary view, display ``created_by`` relations in relations section

   uicfg.primaryview_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations')

   # displays this relation as a list, sets the label, limits the number of results and filters on comments

   uicfg.primaryview_display_ctrl.tag_object_of(

       ('*', 'created_by', 'CWUser'),

       {'vid': 'list', 'label': _('latest comment(s):'), 'limit': True,

        'filter': lambda rset: rset.filtered_rset(lambda x: x.e_schema == 'Comment')})

.. Warning:: with the ``primaryview_display_ctrl`` rtag, the subject or the

   object of the relation is ignored for respectively ``tag_object_of`` or

   ``tag_subject_of``. To avoid warnings during execution, they should be set to

   ``'*'``.

Index view configuration

````````````````````````

:indexview_etype_section:

   entity type category in the index/manage page. May be one of:

      * ``application``

      * ``system``

      * ``schema``

      * ``subobject`` (not displayed by default)

Actions box configuration

`````````````````````````

:actionbox_appearsin_addmenu:

  simple boolean relation tags used to control the "add entity" submenu.

  Relations whose rtag is True will appears, other won't.

.. sourcecode:: python

   # Adds all subjects of the entry_of relation in the add menu of the ``Blog`` primary view

   uicfg.actionbox_appearsin_addmenu.tag_object_of(('*', 'entry_of', 'Blog'), True)

Automatic form configuration

````````````````````````````

Attributes/relations display location

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``uicfg.autoform_section`` specifies where to display a relation in

creation/edition entity form for a given form type.  ``tag_attribute``,

``tag_subject_of`` and ``tag_object_of`` methods for this relation tag expect

two arguments additionally to the relation key: a ``formtype`` and a

``section``.

formtype may be one of:

* ``main``, the main entity form (via the modify action)

* ``inlined``, the form for an entity inlined into another form

* ``muledit``, the table form to edit multiple entities

section may be one of:

* ``hidden``, don't display

* ``attributes``, display in the attributes section

* ``relations``, display in the relations section, using the generic relation

  selector combobox (available in main form only, and not for attribute

  relation)

* ``inlined``, display target entity of the relation in an inlined form

  (available in main form only, and not for attribute relation)

* ``metadata``, display in a special metadata form (NOT YET IMPLEMENTED, subject

  to changes)

By default, mandatory relations are displayed in the ``attributes`` section,

others in ``relations`` section.

Change default fields

^^^^^^^^^^^^^^^^^^^^^

Use ``autoform_field`` to replace the default field type of an attribute.

.. Warning:

   ``autoform_field_kwargs`` should usually be used instead of

   ``autoform_field``. Do not use both methods for the same relation!

Customize field options

^^^^^^^^^^^^^^^^^^^^^^^

In order to customize field options (see :class:`cubicweb.web.formfields.Field`

for a detailed list of options), use ``autoform_field_kwargs``. This rtag takes

a relation triplet and a dictionary as arguments.

.. sourcecode:: python

   # Change the content of the combobox

   # here ``ticket_done_in_choices`` is a function which returns a list of

   # elements to populate the combobox

   uicfg.autoform_field_kwargs.tag_subject_of(('Ticket', 'done_in', '*'), {'sort': False,

                                                  'choices': ticket_done_in_choices})

Overriding permissions

^^^^^^^^^^^^^^^^^^^^^^

``autoform_permissions_overrides`` provides a way to by-pass security checking

for dark-corner case where it can't be verified properly. XXX documents.

"""

__docformat__ = "restructuredtext en"

from warnings import warn

from logilab.common.compat import any

from cubicweb import neg_role

from cubicweb.rtags import (RelationTags, RelationTagsBool, RelationTagsSet,

                            RelationTagsDict, register_rtag, _ensure_str_key)

from cubicweb.schema import META_RTYPES

# primary view configuration ##################################################

def init_primaryview_section(rtag, sschema, rschema, oschema, role):

    if rtag.get(sschema, rschema, oschema, role) is None:

        rdef = rschema.rdef(sschema, oschema)

        if rschema.final:

            if rschema.meta or sschema.is_metadata(rschema) \

                    or oschema.type in ('Password', 'Bytes'):

                section = 'hidden'

            else:

                section = 'attributes'

        else:

            if rdef.role_cardinality(role) in '1+':

                section = 'attributes'

            elif rdef.composite == neg_role(role):

                section = 'relations'

            else:

                section = 'sideboxes'

        rtag.tag_relation((sschema, rschema, oschema, role), section)

primaryview_section = RelationTags('primaryview_section',

                                   init_primaryview_section,

                                   frozenset(('attributes', 'relations',

                                               'sideboxes', 'hidden')))

class DisplayCtrlRelationTags(RelationTagsDict):

    def __init__(self, *args, **kwargs):

        super(DisplayCtrlRelationTags, self).__init__(*args, **kwargs)

        self._counter = 0

    def tag_relation(self, key, tag):

        tag = super(DisplayCtrlRelationTags, self).tag_relation(key, tag)

        self._counter += 1

        tag.setdefault('order', self._counter)

    def tag_subject_of(self, key, tag):

        subj, rtype, obj = key

        if obj != '*':

            self.warning('using explict target type in display_ctrl.tag_subject_of() '

                         'has no effect, use (%s, %s, "*") instead of (%s, %s, %s)',

                         subj, rtype, subj, rtype, obj)

        super(DisplayCtrlRelationTags, self).tag_subject_of((subj, rtype, '*'), tag)

    def tag_object_of(self, key, tag):

        subj, rtype, obj = key

        if subj != '*':

            self.warning('using explict subject type in display_ctrl.tag_object_of() '

                         'has no effect, use ("*", %s, %s) instead of (%s, %s, %s)',

                         rtype, obj, subj, rtype, obj)

        super(DisplayCtrlRelationTags, self).tag_object_of(('*', rtype, obj), tag)

def init_primaryview_display_ctrl(rtag, sschema, rschema, oschema, role):

    if role == 'subject':

        oschema = '*'

        label = rschema.type

    else:

        sschema = '*'

        label = '%s_%s' % (rschema, role)

    rtag.setdefault((sschema, rschema, oschema, role), 'label', label)

    rtag.setdefault((sschema, rschema, oschema, role), 'order', rtag._counter)

primaryview_display_ctrl = DisplayCtrlRelationTags('primaryview_display_ctrl',

                                                   init_primaryview_display_ctrl)

# index view configuration ####################################################

# entity type section in the index/manage page. May be one of

# * 'application'

# * 'system'

# * 'schema'

# * 'hidden'

# * 'subobject' (not displayed by default)

class InitializableDict(dict):

    def __init__(self, *args, **kwargs):

        super(InitializableDict, self).__init__(*args, **kwargs)

        register_rtag(self)

        self.__defaults = dict(self)

    def init(self, schema, check=True):

        self.update(self.__defaults)

        for eschema in schema.entities():

            if eschema.final:

                continue

            if eschema.schema_entity():

                self.setdefault(eschema, 'schema')

            elif eschema.is_subobject(strict=True):

                self.setdefault(eschema, 'subobject')

            else:

                self.setdefault(eschema, 'application')

indexview_etype_section = InitializableDict(

    EmailAddress='subobject',

    # entity types in the 'system' table by default (managers only)

    CWUser='system', CWGroup='system',

    CWPermission='system',

    CWCache='system',

    Workflow='system',

    ExternalUri='system',

    Bookmark='system',

    )

# autoform.AutomaticEntityForm configuration ##################################

def _formsections_as_dict(formsections):

    result = {}

    for formsection in formsections:

        formtype, section = formsection.split('_', 1)

        result[formtype] = section

    return result

def _card_and_comp(sschema, rschema, oschema, role):

    rdef = rschema.rdef(sschema, oschema)

    if role == 'subject':

        card = rdef.cardinality[0]

        composed = not rschema.final and rdef.composite == 'object'

    else:

        card = rdef.cardinality[1]

        composed = not rschema.final and rdef.composite == 'subject'

    return card, composed

class AutoformSectionRelationTags(RelationTagsSet):

    """autoform relations'section"""

    bw_tag_map = {

        'primary':   {'main': 'attributes', 'muledit': 'attributes'},

        'secondary': {'main': 'attributes', 'muledit': 'hidden'},

        'metadata':  {'main': 'metadata'},

        'generic':   {'main': 'relations'},

        'generated': {'main': 'hidden'},

        }

    _allowed_form_types = ('main', 'inlined', 'muledit')

    _allowed_values = {'main': ('attributes', 'inlined', 'relations',

                                'metadata', 'hidden'),

                       'inlined': ('attributes', 'inlined', 'hidden'),

                       'muledit': ('attributes', 'hidden'),

                       }

    def init(self, schema, check=True):

        super(AutoformSectionRelationTags, self).init(schema, check)

        self.apply(schema, self._initfunc_step2)

    @staticmethod

    def _initfunc(self, sschema, rschema, oschema, role):

        formsections = self.init_get(sschema, rschema, oschema, role)

        if formsections is None:

            formsections = self.tag_container_cls()

        if not any(tag.startswith('inlined') for tag in formsections):

            if not rschema.final:

                negsects = self.init_get(sschema, rschema, oschema, neg_role(role))

                if 'main_inlined' in negsects:

                    formsections.add('inlined_hidden')

        key = _ensure_str_key( (sschema, rschema, oschema, role) )

        self._tagdefs[key] = formsections

    @staticmethod

    def _initfunc_step2(self, sschema, rschema, oschema, role):

        formsections = self.get(sschema, rschema, oschema, role)

        sectdict = _formsections_as_dict(formsections)

        if rschema in META_RTYPES:

            sectdict.setdefault('main', 'hidden')

            sectdict.setdefault('muledit', 'hidden')

            sectdict.setdefault('inlined', 'hidden')

        # ensure we have a tag for each form type

        if not 'main' in sectdict:

            if not rschema.final and (

                sectdict.get('inlined') == 'attributes' or

                'inlined_attributes' in self.init_get(sschema, rschema, oschema,

                                                      neg_role(role))):

                sectdict['main'] = 'hidden'

            elif sschema.is_metadata(rschema):

                sectdict['main'] = 'metadata'

            else:

                card, composed = _card_and_comp(sschema, rschema, oschema, role)

                if card in '1+':

                    sectdict['main'] = 'attributes'

                    if not 'muledit' in sectdict:

                        sectdict['muledit'] = 'attributes'

                elif rschema.final:

                    sectdict['main'] = 'attributes'

                else:

                    sectdict['main'] = 'relations'

        if not 'muledit' in sectdict:

            sectdict['muledit'] = 'hidden'