Metadata-Version: 1.1
Name: kotti-settings
Version: 0.2
Summary: Settings configuration for Kotti
Home-page: https://github.com/j23d/kotti_settings
Author: Marco Scheidhuber
Author-email: j23d@jusid.de
License: BSD-derived (http://www.repoze.org/LICENSE.txt)
Description: ==============
        kotti_settings
        ==============
        
        Add a settings configuration to your Kotti site. |build status|_
        
        .. |build status| image:: https://travis-ci.org/j23d/kotti_settings.png
        .. _build status: https://travis-ci.org/j23d/kotti_settings
        
        `Find out more about Kotti`_
        
        Setup
        =====
        
        To activate the ``kotti_settings`` add-on in your Kotti site, you need to
        add an entry to the ``kotti.configurators`` setting in your Paste
        Deploy config.  If you don't have a ``kotti.configurators`` option,
        add one.  The line in your ``[app:main]`` (or ``[app:kotti]``, depending on how
        you setup Fanstatic) section could then look like this::
        
            kotti.configurators = kotti_settings.kotti_configure
        
        The add-on adds a new configuration page to save settings for your module or
        accross different modules. It adds a new submenupoint named "Settings" to the
        menupoint "Site Setup". Every setting collection is presented in one tab. It
        is intended to use one tab for a module, but it is also possible to use
        multiple tabs if you have the need for a more extended structure.
        
        You can choose between two modes to set up your settings. With the "dict mode"
        you have a very easy and straightforward option to set up the settings. If you
        need more advanced forms you can set up an own schema.
        
        A setting tab is set up with with a dictionary. Here you define a name and a
        title for your tab, what are required. Optional arguments are success_message,
        either settings or schema, schema_factory and use_csrf_token.
        
        Define your settings in a dictionary::
        
        	TestSettings = {
                'name': 'test_settings',
                'title': "Testsettings",
                'description': "Some description for my settings",
                'success_message': u"Successfully saved test settings.",
                'settings': [
                    {'type': 'String',
                     'name': 'testsetting_1',
                     'title': 'Test 1',
                     'description': 'a test setting',
                     'default': '', },
                    {'type': 'Integer',
                     'name': 'testsetting_2',
                     'title': 'Test 2',
                     'description': 'again a test setting',
                     'default': 23, }]}
        
        Define your settings with a schema::
        
            class StringSchemaNode(colander.SchemaNode):
                name = 'a_string'
                title = 'hello'
                default = 'hello world'
        
            class RangedIntSchemaNode(colander.SchemaNode):
                name = 'range_int'
                validator = colander.Range(0, 10)
                default = 5
                title = 'Ranged Int'
        
            class TestSchema(colander.MappingSchema):
                string = StringSchemaNode(colander.String())
                ranged_int = RangedIntSchemaNode(colander.Int())
        
            TestSettings = {
                'name': 'test_settings',
                'title': "Testsettings",
                'description': "Some description for my settings",
                'success_message': u"Successfully saved test settings.",
                'schema_factory': TestSchema
            }
        
        
        To get your configuration registered within ``kotti_settings`` add the
        settings in a populator in your add-on. Have a look to the Kotti documentation
        to get more informations for populators_ and to see an example_.
        
        
        Add your settings configuration within a populator, e.g. in a file named populate.py::
        
            def populate():
                from kotti_settings.util import add_settings
                add_settings(TestSettings)
        
        and add this to your configuration::
        
            def kotti_configure(settings):
                settings['kotti.populators'] += ' my_addon.populate.populate'
        
        or directly to your ini file::
        
            kotti.populators = my_addon.populate.populate
        
        
        To get your setting back into your code you use the following::
        
            from kotti_settings.util import get_setting
        
            first_test_setting = get_setting('test_setting_1')
        
        Events
        ------
        
        Before and after the settings are saved events for handling the changes are fired. To subscribe
        to the events use something like::
        
            from pyramid.events import subscriber
            from kotti_settings.events import SettingsAfterSave
        
            @subscriber(SettingsAfterSave)
            def do_something_when_settings_saved(event):
                # Check if the settings for this module was saved.
                if not event.module == __package__:
                    return
                my_fancy_thing()
        
        Default schemas
        ---------------
        
        ``kotti_settings`` provides some default schemas that you can use directly in your code and for
        example purposes. Currently there are two schemas implemented, one to choose in what slot the
        widget should be shown and another one to set the visibility of the widget. To use it in your
        addon place something like the following in your populator::
        
            from kotti.views.slots import assign_slot
            from kotti_settings.config import SlotSchemaNode
            from kotti_settings.config import ShowInContextSchemaNode
            from kotti_settings.util import add_settings
            from kotti_settings.util import get_setting
            from kotti_myaddon import _
        
            class MyWidgetSchema(colander.MappingSchema):
                slot = SlotSchemaNode(colander.String())
                show_in_context = ShowInContextSchemaNode(colander.String())
        
            MyAddonSettings = {
                'name': 'myaddon_settings',
                'title': _(u'My Addon Settings'),
                'description': _(u"Settings for my addon"),
                'success_message': _(u"Successfully saved my addon settings."),
                'schema_factory': MyAddonSchema,
            }
        
            def populate():
                add_settings(MyAddonSettings)
        
        You have a full example e.g. in the addon kotti_tagcloud_.
        
        
        .. _Find out more about Kotti: http://pypi.python.org/pypi/Kotti
        .. _populators: http://kotti.readthedocs.org/en/latest/developing/configuration.html#kotti-populators
        .. _example: http://kotti.readthedocs.org/en/latest/developing/frontpage-different-template.html
        .. _kotti_tagcloud: https://pypi.python.org/pypi/kotti_tagcloud
        
        
        Changelog
        =========
        
        0.2(2013-11-12)
        ---------------
        
        * Only scan the needed views file.
        * Added MANIFEST.in to get rid of the local folder.
        
        
        0.1(2013-10-19)
        ---------------
        
        * Added documentation for the default schemas.
        * Change the implementation to check what settings form was saved.
        * Added new util method 'set_setting' where value transformations are handled.
        * Removed not needed fanstatic resources.
        * Changed the internal name of the forms to be more unique.
        * Reinitialize chosen elements when tab is shown.
        * Convert boolean to 'true' or 'false' to meet the requirements of deform's checkbox widget.
        
        
        0.1b4(2013-05-02)
        -----------------
        
        * Added a helper method for one of the default setting schemas.
        * Only save the settings from the submitted form.
        * Set the saved form as the active one.
        * Added possibility to remove a widget only from a specific slot.
        
        
        0.1b3(2013-04-18)
        ------------------
        
        * Fix: Settings defined in a schema also have to be initialized.
        
        
        0.1b2(2013-04-18)
        -----------------
        
        * Added possibility to remove a widget from the slots.
        * Added two default schemas, one to select the slot for the widget and one
          to set where to show the widget.
        
        
        0.1b1(2013-03-29)
        -----------------
        
        * Added event handling for callbacks before and after the settings are saved.
        
        
        0.1a3(2013-03-13)
        -----------------
        
        * Only take the module name itself into account for the setting name.
        
        
        0.1a2(2013-03-11)
        -----------------
        
        * Added util method get_setting as default way to get a setting.
        
        
        0.1a1(2013-03-06)
        -----------------
        
        * Initial release.
        
Keywords: kotti ui settings cms pyramid pylons
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Pylons
Classifier: Framework :: Pyramid
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: User Interfaces
