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

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

update readme with indexing info

  • Property svn:eol-style set to native
File size: 6.8 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 have associated archetypes schemas, a flavor aware content
61   object has a schema composed of its class schema and all of its
62   applied flavor schemas.
63
64 - what flavors can be applied to a given flavor aware content is
65   configurable via interface specification, a default adapter is also
66   available. [ adapter for IFlavorProvider ]
67
68 - flavors are ordered. [ stored in ordered format, either ordered
69   markers, or explict ordered attribute with resolvable flavor names ]
70
71 - a content has a primary flavor ( the first flavor of the ordered set ).
72   [ we may do away with this notion, use cases for it are welcome ]
73
74 - flavors can give additional actions to content, based on registered
75   browser menus definitions for flavor views.
76
77 - events are fired on invalidation
78
79 - we attempt an intelligent cache using class and provided by for
80   schema retrieval. [ not yet ]
81
82
83ZCML
84----
85 a zcml directive is used to add flavors to the system, there are
86 quite a few optional arguements to support various use cases. a fully
87 specified directive follows.
88
89 <ore:content_flavor
90    name="examples.example_flavor"
91    title="The Example Flavor"
92    description="A flavor used for examples"
93    for="Products.Examples.interfaces.IExampleContent"
94    adapter="Products.Examples.flavor.ExampleFlavor"
95    icon="example_flavor.png"
96    archetype_schema="Products.Examples.schemata.ExampleFlavorSchema"
97    marker="Products.Example.interfaces.IExampleFlavorMarker"/>
98
99
100Required Attributes
101===================
102
103 - name .. a qualified name to the interface, this is used in adapter
104           registrations from IFlavorAware to the Flavor
105
106 - title .. a user displayed string for applying the flavor.
107
108Optional Attributes
109===================
110
111 - description .. an additional user information string describing the flavor.
112
113 - icon .. optional icon specified for flavor
114
115 - for .. an optional specification of which interfaces a flavor is
116   registerable for, if not specified the flavor is aware to all
117   content implementing IFlavorAware.
118
119 - adapter .. optional specification for an adapter factory for IFlavor
120
121 - archetype_schema .. optional archetypes schema to apply to content
122
123 - marker .. optional z3 marker interface to apply to content
124
125
126Applying Views to Flavors
127-------------------------
128
129To apply a flavor based view to a content object, the flavor directive
130marker attribute must be specified. Additional views registered to
131that marker will now be available to
132
133An example of configuring a flavor view which will appear as a content tab.
134
135  <browser:page
136      for="Products.Examples.interfaces.IExampleFlavorMarker"
137      name="rabbits"
138      template="example_settings.pt"
139      permission="cmf.ModifyPortalContent"
140      menu="object"
141      title="Example Settings"
142      />
143
144now when the examples.example_flavor  is applied to the content, the
145content will get new views and actions from the flavor.
146
147Flavor Management UI
148--------------------
149
150There are two options for flavor management user interface, one as
151part of a content's archetypes schema and mixing in
152content.FlavorAwareContent, in general this is discouraged since it
153changes schemas right after a user adds or edits content,
154
155potentially nescitating reediting. [ should remove in the future,
156doesn't maintain ordering and bad user semantic ]
157
158the recommended integration is via a content view, which is by default
159setup for IFlavorAware objects. it utilizes formlib and a z3
160orderedmultiselection widget to maintain flavor order which is
161significant in determining primary flavor [should remove this
162notion, and just loop on flavors till first icon is found, as thats
163the only consumer of this property ]
164
165Indexing Flavor Schemas
166-----------------------
167
168additional content AT schema can be indexed utilizing zcatalog, with the
169caveat that its not possible to use them for brain metadata (at least
170not for access from restricted code ) and that care needs to be taken
171to specify attributes indexed on the index to point to the accessor.
172in the general case that a class accessor is not specified, the
173attribute name to index is _v_accessor_name. when class accessors are
174present on some content, the index needs capabilities to index more
175than one attribute.
176
177
178
179Component Responsibilities
180--------------------------
181
182FlavorAware
183===========
184
185aware.py
186
187  - schema delegator to adapter for FlavorSchemaProvider
188
189  - has an icon delegator, delegates to primary flavor or superclass
190
191  - flavor accessor/mutator/vocabulary delegates to flavor provider
192
193FlavorSchemaProvider
194====================
195
196schema.py
197
198  - provide archetypes schema composition and instance method generation.
199
200Flavor
201======
202
203flavor.py
204
205  - archetypes schema
206
207  - icon
208 
209  - z3 marker interface
210
211FlavorProvider (Adapter)
212========================
213
214provider.py
215
216  - introspectable for flavors on a given context
217
218  - api for mutating flavors on an instance.
219   
220  - vocabulary adapter for pulling interfaces for a given context
221
222  - default implementation uses annotations
223
224
225FlavorVocabulary
226=============
227
228  - vocabulary for flavors management ui
229
230Todo
231----
232
233 - rewrite unit tests to be independent of external projects
234
235License
236-------
237
238 GPL
239
240Credits
241-------
242 Developed by ObjectRealms - info at objectrealms dot net
243
244 (C) Copyright 2006 ObjectRealms, LLC
245 
246
247
248
249
250
251
252
253 
Note: See TracBrowser for help on using the repository browser.