Author: jmorliaguet
Date: Sun Nov  6 16:58:22 2005
New Revision: 29021

Added:
   z3lab/cpsskins/branches/jmo-perspectives/doc/setup.txt   (contents, props 
changed)
Log:

- brainstorming ideas about application setup



Added: z3lab/cpsskins/branches/jmo-perspectives/doc/setup.txt
==============================================================================
--- (empty file)
+++ z3lab/cpsskins/branches/jmo-perspectives/doc/setup.txt      Sun Nov  6 
16:58:22 2005
@@ -0,0 +1,146 @@
+
+$Id$
+
+=================
+APPLICATION SETUP
+=================
+
+    >>> from zope import component
+    >>> from cpsskins import configuration
+
+Description
+===========
+
+This document describes different strategies for application setup and
+configuration.
+
+
+A) File-system configuration
+----------------------------
+
+In this type of configuration the information is stored on the filesystem
+(typically in ZCML, in XPDL, etc.). From the user's perspective the information
+is read-only. The files on the filesystem must be modified and the information
+be reloaded or the server be restarted for changes to take effect.
+
+Example
+~~~~~~~
+
+We have access key definition in ZCML::
+
+    <accesskey
+        key="K"
+        url="@@someurl.html"
+    />
+
+it is represented by an AccessKey configuration object::
+
+    >>> accesskey = AccessKey(key=u'K', url=u'@@someurl.html')
+
+
+and it is registered as a global utility in metaconfigure.py::
+
+    >>> name = u'K shortcut'
+    >>> component.provideUtility(accesskey, configuration.IAccessKey, name)
+
+
+as a result, the access key is available as a global utility::
+
+    >>> component.queryUtility(configuration.IAccessKey, name)
+    AccessKey(u'K', u'@@someurl.html')
+
+
+The 'AccessKey' object is only used to hold a unique piece of information;
+it is not meant to be used as a factory to create multiple objects in the ZODB.
+
+
+B) TTW configuration
+--------------------
+
+This type of setup the configuration is done through-the-web. The objects that
+are set up are the same as the objects described in the filesystem-based
+configuration. They are registered as local utilities instead::
+
+    >>> sm = getSiteManager(context)
+    >>> sm.provideUtility(accesskey, configuration.IAccessKey, name)
+
+    >>> queryUtility(configuration.IAccessKey, name, context)
+    AccessKey(u'K', u'@@someurl.html')
+
+
+C) Instanciated objects
+-----------------------
+
+Instanciated objects are created by users, they are not registered as
+utilities (e.g. styles, individual portlets, ...), but they may be converted
+into utilities.
+
+
+Use cases
+=========
+
+Create a configuration item TTW
+-------------------------------
+
+This consists in registering local utilities that provide the interface of
+the object to configure. Configurations are available locally (inside a same
+theme management folder)
+
+Customize a file-system configuration item
+------------------------------------------
+
+This consists in copying a component registered as a global utility into a
+local utility.
+
+Uncustomize a configuration item
+--------------------------------
+
+The local utility is deactivated and removed from the theme management folder.
+
+Export a TTW configuration to the filesystem
+--------------------------------------------
+
+Use a tool to export a component registed as a local utility to ZCML or to any
+descriptive configuration format used for setting up the application.
+
+
+Convert an instanciated object into a setting
+---------------------------------------------
+
+to be defined...
+
+A typical use case is when an instanciated object is to be used as a global 
+setting for the application.
+
+Illustration:
+
+A site designer creates a box style and wants to turn it into a preset so
+that it can be used by the application as the default box style for a site::
+
+There is a Style object (ZODB instance) created through-the-web::
+
+    >>> style = Style(properties={u'color': u'red', u'font': u'sans-serif'})
+    >>> style.items()
+    [(u'color': u'red'), (u'font': u'sans-serif')]
+
+it needs to be streamlined and be converted into a configuration setting:
+
+    <style
+        name="Some style"
+        provider="Some style provider">
+
+       <property name="color" value="red" />
+       <property name="font" value="sans-serif" />
+
+    </style>
+
+then it can be registered as a local utility::
+
+    >>> style = configuration.Style(
+    ...     name=u'Some style'
+    ...     provider=u'Some style provider',
+    ...     properties={u'color': u'red', u'font': u'sans-serif'})
+
+    >>> sm = getSiteManager(context)
+    >>> sm.provideUtility(style, configuration.IStyle, name)
+
-- 
http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins

Reply via email to