#: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

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

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'

            if sectdict['main'] == 'attributes':

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