source: Products.ContentFlavors/trunk/readme.txt @ 1679

Last change on this file since 1679 was 1679, checked in by hazmat, 12 years ago

add field overriding, using first one wins rules

  • Property svn:eol-style set to native
File size: 6.0 KB
Line 
1---------------
2Content Flavors
3----------------
4
5What are flavors?
6-----------------
7
8 are bits of behavior and schema that we can add to content.
9 we can gain additional access to icons, actions, views, adapters,
10 and at schemas via adding a flavor to a piece of content.
11
12 A flavor is composed of a number of optional parts based on
13 requirements, archetypes schemas to compose, marker interfaces to
14 apply, etc. see the zcml section, for a complete definition.
15
16Using Flavors
17-------------
18
19 Plone content that wants to fully utilize flavors, should mixin the
20 minimal Products.ContentFlavors.aware.FlavorAware class. This
21 provides the schema lookup/composition and icon delegation.
22 
23 Additionally, a default view for modifying flavors is registered for
24 IFlavorAware which the mixin provides.
25
26
27Installation
28------------
29
30Content Flavors bridges a number of frameworks, and requires a
31specific version to operate. Its tested on and requires
32
33 - Plone 2.5
34 - Zope 2.9.4
35 - Five 1.4
36 - CMFonFive 1.3.3
37
38Status
39------
40
41Extremely New, needs some kicking in of tires.
42
43- the underhood machinery works pretty well.
44
45- however, the ui for flavor management, has some minor issues atm
46  though both mechanisms are useable (via at content editing, or a z3 view)
47
48- the ability to utilize custom geticon requires a custom folder
49  contents as plone 2.5 hardcodes icons to content-type css (ditto for navtree)
50 
51
52System Properties
53-----------------
54
55 - a flavor is defined in zcml, it has a name, icon, description,
56   a marker z3 interface, and an archetypes schema.
57   
58 - a content object can have zero or more flavors.
59
60 - flavors are ordered. [ stored in ordered format, either ordered
61   markers, or explict ordered attribute with resolvable flavor names ]
62
63 - a content has a primary flavor ( the first flavor of the ordered set ).
64
65 - flavors have associated archetypes schemas, a flavor aware content
66   object has a schema composed of its class schema and all of its
67   applied flavor schemas.
68
69 - what flavors can be applied to a given flavor aware content is
70   configurable via interface specification, a default adapter is also
71   available. [ adapter for IFlavorProvider ]
72
73 - flavors can give additional actions to content, based on registered
74   browser menus definitions for flavor views.
75
76 - events are fired on invalidation
77
78 - we attempt an intelligent cache using class and provided by for
79   schema retrieval.
80
81
82ZCML
83----
84 a zcml directive is used to add flavors to the system, there are
85 quite a few optional arguements to support various use cases. a fully
86 specified directive follows.
87
88 <ore:content_flavor
89    name="examples.example_flavor"
90    title="The Example Flavor"
91    description="A flavor used for examples"
92    for="Products.Examples.interfaces.IExampleContent"
93    adapter="Products.Examples.flavor.ExampleFlavor"
94    icon="example_flavor.png"
95    archetype_schema="Products.Examples.schemata.ExampleFlavorSchema"
96    marker="Products.Example.interfaces.IExampleFlavorMarker"/>
97
98
99Required Attributes
100===================
101
102 - name .. a qualified name to the interface, this is used in adapter
103           registrations from IFlavorAware to the Flavor
104
105 - title .. a user displayed string for applying the flavor.
106
107Optional Attributes
108===================
109
110 - description .. an additional user information string describing the flavor.
111
112 - icon .. optional icon specified for flavor
113
114 - for .. an optional specification of which interfaces a flavor is
115   registerable for, if not specified the flavor is aware to all
116   content implementing IFlavorAware.
117
118 - adapter .. optional specification for an adapter factory for IFlavor
119
120 - archetype_schema .. optional archetypes schema to apply to content
121
122 - marker .. optional z3 marker interface to apply to content
123
124
125Applying Views to Flavors
126-------------------------
127
128To apply a flavor based view to a content object, the flavor directive
129marker attribute must be specified. Additional views registered to
130that marker will now be available to
131
132An example of configuring a flavor view which will appear as a content tab.
133
134  <browser:page
135      for="Products.Examples.interfaces.IExampleFlavorMarker"
136      name="rabbits"
137      template="example_settings.pt"
138      permission="cmf.ModifyPortalContent"
139      menu="object"
140      title="Example Settings"
141      />
142
143now when the examples.example_flavor  is applied to the content, the
144content will get new views and actions from the flavor.
145
146Flavor Management UI
147--------------------
148
149There are two options for flavor management user interface, one as
150part of a content's archetypes schema and mixing in
151content.FlavorAwareContent, in general this is discouraged since it
152changes schemas right after a user adds or edits content,
153
154potentially nescitating reediting. [ should remove in the future,
155doesn't maintain ordering and bad user semantic ]
156
157the recommended integration is via a content view, which is by default
158setup for IFlavorAware objects. it utilizes formlib and a z3
159orderedmultiselection widget to maintain flavor order which is
160significant in determining primary flavor [should remove this
161notion, and just loop on flavors till first icon is found, as thats
162the only consumer of this property ]
163
164
165Component Responsibilities
166--------------------------
167
168FlavorAware
169===========
170
171aware.py
172
173  - schema delegator to adapter for FlavorSchemaProvider
174
175  - has an icon delegator, delegates to primary flavor or superclass
176
177  - flavor accessor/mutator/vocabulary delegates to flavor provider
178
179FlavorSchemaProvider
180====================
181
182schema.py
183
184  - provide archetypes schema composition and instance method generation.
185
186Flavor
187======
188
189flavor.py
190
191  - archetypes schema
192
193  - icon
194 
195  - z3 marker interface
196
197FlavorProvider (Adapter)
198========================
199
200provider.py
201
202  - introspectable for flavors on a given context
203
204  - api for mutating flavors on an instance.
205   
206  - vocabulary adapter for pulling interfaces for a given context
207
208  - default implementation uses annotations
209
210
211FlavorVocabulary
212=============
213
214  - vocabulary for flavors management ui
215
216Todo
217----
218
219 - rewrite unit tests to be independent of external projects
220
221
222
223
224
225
226
227
228
229
230 
Note: See TracBrowser for help on using the repository browser.