Metadata-Version: 2.1
Name: zope.app.preference
Version: 3.8.1
Summary: User Preferences Framework ZMI UI
Home-page: http://pypi.python.org/pypi/zope.app.preference
Author: Zope Corporation and Contributors
Author-email: zope-dev@zope.org
License: ZPL 2.1
Description: This package provides a UI to maintain hierarchical user preferences
        in the ZMI.
        
        .. contents::
        
        ===================
        zope.app.preference
        ===================
        
        This package provides a user interface in the ZMI, so the user can edit
        the preferences.
        
        Set up
        ------
        
        To show the user interface functions we need some setup beforehand:
        
          >>> from zope.testbrowser.testing import Browser
          >>> browser = Browser()
        
        As the preferences cannot be defined through the web we have to define
        them in python code:
        
          >>> import zope.interface
          >>> import zope.schema
          >>> class IZMIUserSettings(zope.interface.Interface):
          ...     """Basic User Preferences"""
          ...
          ...     email = zope.schema.TextLine(
          ...         title=u"E-mail Address",
          ...         description=u"E-mail Address used to send notifications")
          ...
          ...     skin = zope.schema.Choice(
          ...         title=u"Skin",
          ...         description=u"The skin that should be used for the ZMI.",
          ...         values=['Rotterdam', 'ZopeTop', 'Basic'],
          ...         default='Rotterdam')
          ...
          ...     showZopeLogo = zope.schema.Bool(
          ...         title=u"Show Zope Logo",
          ...         description=u"Specifies whether Zope logo should be displayed "
          ...                     u"at the top of the screen.",
          ...         default=True)
        
        The preference schema is usually registered using a ZCML statement:
        
          >>> from zope.configuration import xmlconfig
          >>> import zope.app.preference
          >>> context = xmlconfig.file('meta.zcml', zope.app.preference)
        
          >>> context = xmlconfig.string('''
          ...     <configure
          ...         xmlns="http://namespaces.zope.org/zope"
          ...         i18n_domain="test">
          ...
          ...       <preferenceGroup
          ...           id="ZMISettings"
          ...           title="ZMI Settings"
          ...           schema="zope.app.preference.README.IZMIUserSettings"
          ...           category="true"
          ...           />
          ...
          ...     </configure>''', context)
        
        Editing Preferences
        -------------------
        
        The preferences are accessable in the ``++preferences++`` namespace:
        
          >>> browser.open('http://localhost/++preferences++')
        
        The page shows a form which allows editing the preference values:
        
          >>> browser.getControl('E-mail').value = 'hans@example.com'
          >>> browser.getControl('Skin').displayOptions
          ['Rotterdam', 'ZopeTop', 'Basic']
          >>> browser.getControl('Skin').displayValue = ['ZopeTop']
          >>> browser.getControl('Show Zope Logo').selected
          True
          >>> browser.getControl('Show Zope Logo').click()
        
        After selecting `Change` the values get persisted:
        
          >>> browser.getControl('Change').click()
          >>> browser.url
          'http://localhost/++preferences++/@@index.html'
          >>> browser.getControl('E-mail').value
          'hans@example.com'
          >>> browser.getControl('Skin').displayValue
          ['ZopeTop']
          >>> browser.getControl('Show Zope Logo').selected
          False
        
        The preference group is shown in a tree. It has a link to the form:
        
          >>> browser.getLink('ZMISettings').click()
          >>> browser.url
          'http://localhost/++preferences++/ZMISettings/@@index.html'
          >>> browser.getControl('E-mail').value
          'hans@example.com'
        
        
        Preference Group Trees
        ----------------------
        
        The preferences would not be very powerful, if you could create a full
        preferences. So let's create a sub-group for our ZMI user settings, where we
        can adjust the look and feel of the folder contents view:
        
          >>> class IFolderSettings(zope.interface.Interface):
          ...     """Basic Folder Settings"""
          ...
          ...     shownFields = zope.schema.Set(
          ...         title=u"Shown Fields",
          ...         description=u"Fields shown in the table.",
          ...         value_type=zope.schema.Choice(['name', 'size', 'creator']),
          ...         default=set(['name', 'size']))
          ...
          ...     sortedBy = zope.schema.Choice(
          ...         title=u"Sorted By",
          ...         description=u"Data field to sort by.",
          ...         values=['name', 'size', 'creator'],
          ...         default='name')
        
        And register it:
        
          >>> context = xmlconfig.string('''
          ...     <configure
          ...         xmlns="http://namespaces.zope.org/zope"
          ...         i18n_domain="test">
          ...
          ...       <preferenceGroup
          ...           id="ZMISettings.Folder"
          ...           title="Folder Content View Settings"
          ...           schema="zope.app.preference.README.IFolderSettings"
          ...           />
          ...
          ...     </configure>''', context)
        
        The sub-group is displayed inside the parent group as a form:
        
          >>> browser.reload()
          >>> browser.getControl('Shown Fields').displayOptions
          ['name', 'size', 'creator']
          >>> browser.getControl('Shown Fields').displayValue
          ['name', 'size']
          >>> browser.getControl('Shown Fields').displayValue = ['size', 'creator']
          >>> browser.getControl('Sorted By').displayOptions
          ['name', 'size', 'creator']
          >>> browser.getControl('Sorted By').displayValue = ['creator']
        
        Selecing `Change` persists these values, too:
        
          >>> browser.getControl('Change').click()
          >>> browser.getControl('Shown Fields').displayValue
          ['size', 'creator']
          >>> browser.getControl('Sorted By').displayValue
          ['creator']
        
        
        =======
        CHANGES
        =======
        
        3.8.1 (2010-06-15)
        ------------------
        
        - Fixed BBB imports which pointed to a not existing `zope.preferences`
          package.
        
        
        3.8.0 (2010-06-12)
        ------------------
        
        - Depend on split out `zope.preference`.
        
        
        3.7.0 (2010-06-11)
        ------------------
        
        - Added HTML labels to ZMI forms.
        
        - Removed `edit.pt` as it seems to be unused.
        
        - Added tests for the ZMI views.
        
        
        3.6.0 (2009-02-01)
        ------------------
        
        - Use ``zope.container`` instead of ``zope.app.container``.
        
        
        3.5.0 (2009-01-17)
        ------------------
        
        - Got rid of ``zope.app.zapi`` dependency, replacing its uses with direct
          imports from original places.
        
        - Change mailing address from zope3-dev to zope-dev, as the first one
          is retired now.
        
        - Fix tests for python 2.6.
        
        - Remove zpkg stuff and zcml include files for
          old mkzopeinstance-based instances.
        
        
        3.4.1 (2007-10-30)
        ------------------
        
        - Avoid deprecation warnings for ``ZopeMessageFactory``.
        
        
        3.4.0 (2007-10-25)
        ------------------
        
        - Initial release independent of the main Zope tree.
        
Keywords: zope3 user preference
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Framework :: Zope3
Provides-Extra: test
