## $Id: interfaces.py 7333 2011-12-12 07:01:54Z henrik $
##
## Copyright (C) 2011 Uli Fouquet & Henrik Bettermann
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##
"""Interfaces for viewing components.
"""
from zope import schema
from zope.interface import Interface, Attribute
from waeup.sirp.interfaces import (
    ISIRPObject, IUniversity, IUsersContainer, IDataCenter)
from waeup.sirp.university.interfaces import (
    IFacultiesContainer, IFaculty, IFacultyAdd, IDepartment, IDepartmentAdd,
    ICoursesContainer, ICourse, ICourseAdd, ICertificatesContainer,
    ICertificate, ICertificateAdd, ICertificateCourse, ICertificateCourseAdd)

class IBreadcrumb(Interface):
    """Provide breadcrumbs.
    """
    title = Attribute("Context description")
    viewname = Attribute("The viewname, for which the breadcrumb is provided.")
    parent_viewname = Attribute("The viewname of the parent to use.")
    parent = Attribute("The parent object.")
    context = Attribute("The context of the breadcrumb.")
    target = Attribute("The link target.")

class IBreadcrumbIgnorable(Interface):
    """A marker interface for breadcrumbs that should be skipped in output.

    If a breadcrumb wants to be skipped in real output (for instance,
    because it is set on a layer in site hierarchy that should not be
    accessed by users), it can also provide this interface. The
    getBreadcrumbList() function defined here will exclude IIgnorables
    by default.
    """
    pass

class IBreadcrumbContainer(Interface):
    """A container of breadcrumbs.
    """
    def __iter__():
        """Allow iteration over the container.
        """

    def getList():
        """Get the list of breadcrumbs as real Python list.
        """
class ITheme(Interface):
    """An theme or 'skin'.

    Themes are basically collections of CSS- and/or JavaScript files
    stored somewhere. In Grok-contexts these files can be registered
    as 'resources' (see :mod:`waeup.sirp.browser.resources`).

    Furthermore, to make themes selectable and distinctable from each
    other we assign them short descriptions.

    Themes should be registered as named utilities so that they can be
    defined also in third-party packages and be looked up by other
    components like theme-selectors.
    """
    description = schema.TextLine(
        title = u'Description',
        description = u'Short description of the theme for choice fields',
        required = False,
        )

    def getResources():
        """Get resources of the theme.

        Deliver a list of resources that must be included in a web page to
        let it be rendered in the theme's style.

        A resource is normally defined in the `resources` module. If a
        theme needs several of them which normally do not depend on
        each other then all these resources can be returned by this
        method. Normally, you will only return one resource.

        These resources will (if the theme is selected) be `need()`-ed
        by the `update()` method of the general site layout.
        """

class ICaptchaRequest(Interface):
    """A set of data required to verify captcha solutions.

    To solve a captcha we need at least a solution. Many types of
    captchas might also need a challenge to compare whether the
    solution is correct.
    """
    solution = schema.TextLine(
        title = u'Solution string a user entered',
        default = None,
        )
    challenge = schema.TextLine(
        title = u'The challenge the solution might match',
        default = None,
        )

class ICaptchaResponse(Interface):
    """A formalized response for captcha solutions.
    """
    is_valid = schema.Bool(
        title = u'Indicates validity of entered captcha data.',
        default = False,
        )
    error_code = schema.TextLine(
        title = u'Error when trying to validate entered captcha data.',
        description = u'Error codes are not expected to be readable strings.',
        default = None,
        )

class ICaptcha(Interface):

    def verify(request):
        """Verify data entered in an HTTP request.

        Expects some IHTTPRequest object and returns an
        ICaptchaResponse indicating that the solution was correct or
        not.

        If the solution could not be verified (this might also happen
        because of technical reasons), the response might contain an
        error code.
        """

    def display(error_code=None):
        """Returns a piece of HTML code that displays the captcha.

        The generated HTML code might depend on any previous error
        code as returned from :meth:`verify`.

        The code is expected to appear inside a ``<form>``. It
        therefore should not contain a ``<form>`` nor any submit
        buttons.
        """

class ICaptchaConfig(Interface):
    """Any type of captcha might need some configuration data.

    By default we require no configuration data.
    """

class ICaptchaManager(Interface):
    """A chooser that collects available captchas.
    """
    def getAvailCaptchas():
        """Return a dict of available captchas with registered names as keys.
        """

    def getCaptcha():
        """Get captcha chosen for a certain site or default.
        """
