Annotation of kupuMPIWG/doc/TEMPLATE-SYSTEM.txt, revision 1.1.1.1
1.1 dwinter 1: ==========================
2: The kupu Templating System
3: ==========================
4:
5: Problem
6: =======
7:
8: kupu is an editor with many features, many of them optional or
9: specific to certain integration implementations. While it is fairly
10: easy to maintain the JavaScript side of features through separate
11: files, the HTML template has to be custom constructed for every
12: feature combination.
13:
14: Kupu 1.0 thus comes with five different templates. Zope-based
15: applications would just require one template because they could turn
16: certain parts of the template on and off by filling ZPT
17: slots. However, applications not using Zope Page Templates (ZPTs) have
18: to customize one of the provided templates. That not only means manual
19: editing of the templates in order to configure the feature set, it
20: also means the lack of an automatic update when a new kupu version is
21: released.
22:
23:
24: Goals
25: -----
26:
27: We want to...
28:
29: * involve as few files as possible when adding a new feature to
30: kupu. We preferrably only want to add a file for the JavaScript
31: part of the feature and a file for the template part of the
32: feature.
33:
34: * be able to disable a feature whenever we want under any
35: circumstance.
36:
37: * allow and encourage third party developers to develop plugins
38: (i.e. new features) for kupu that can be distributed outside the
39: main kupu integration and yet be included without manual
40: adjustments.
41:
42: * be able to include platform specific markup when necessary.
43:
44: * rely on templating standards (XML, XSLT, XInclude, etc.)
45:
46: It is clear, that a system-indepentend templating system is needed to
47: ease kupu's integration into other systems and any customization that
48: is required by such a process.
49:
50:
51: Definitions
52: -----------
53:
54: Slot
55:
56: A position in a template, at which markup can be inserted. Example:
57: the HTML header, the HTML body.
58:
59: Feature
60:
61: A bundle of code and markup providing a certain set of
62: functionality. Examples for basic features are: the editor frame,
63: toolbar with buttons, colorchooser, synchronous form-based or
64: asynchronous document-centric editing support. Examples for more
65: advanced and optional features are: save on part, autosave, context
66: menu, source editing, library drawer.
67:
68: Part
69:
70: A part of a Feature. While order usually does not matter when
71: writing JavaScript prototypes (or including them from a file), order
72: in a template *does* matter. Therefore, a Feature can consist of
73: different parts which are distributed throughout the template at the
74: appropriate places (Slots). Example: The parts of the source edit
75: feature are the button in the toolbar that enables source editing
76: and the function that is called when the button is clicked.
77:
78: Implementation
79:
80: Combination of target platform specific Features or Parts of
81: Features. The way Features are implemented might vary througout
82: different integration layers, due to the requirements of the target
83: platforms. Examples of Implementations are: Default (the default set
84: of Features), Zope (re-implementation of certain features for Zope
85: integration), Plone, Silva, Apache Lenya, MMBase, etc.
86:
87: Distribution
88:
89: Set of Feature definitions or Feature disablings in the context of a
90: certain Implementation or order of Implementations. Distributions
91: can not only differ from integration layer to integration layer, but
92: also be customized for every application or system Kupu is part
93: of. Kupu thus only provides *default* distributions, e.g.:
94: Distribution for default Features, Distribution for Plone,
95: Distribution for Silva, Distributon for Silva, etc. Web Developer
96: XYZ might choose to make a custom distribution for the application
97: (s)he's building for customer ABC.
98:
99:
100: Whenever the above defined words appear in the text below, their first
101: letter is capitalized. Otherwise, the term is used in its conventional
102: meaning.
103:
104:
105: Perceptions
106: -----------
107:
108: * An Implementation overrides one or more features defined by default
109: Implementations or defines new features
110:
111: * Wiring Parts to Slots is Distribution-specific.
112:
113: * Implementation Order is Distribution-specific.
114:
115: * Feature enabling/disabling is Distribution-specific, but usually
116: more specific to the target application than to the pre-packaged
117: Distribution.
118:
119:
120: Proposal
121: ========
122:
123:
124: File system structure
125: ---------------------
126:
127: kupu's former main template (kupumacros.html) is split into logical
128: chunks resembling Features and Parts as defined above. Each Feature
129: and all its parts resides in an XML file with the file ending '.kupu'.
130: All features of an Implementation reside in the same directory. The
131: main kupu distribution includes a directory named 'default'. It
132: contains a default set of Features in their default Implementation.
133: Platform specific markup resides in other Implementation directories.
134:
135: A Distribution is represented in an XML file typically named
136: 'dist.kupu'. It defines an order in which Features are looked up in
137: Implementations and can optionally disable Features.
138:
139: A system consisting of XSLT templates is used to parse a Distribution
140: configuration file and construct markup custom to that particular
141: Distribution. The XInclude standard is used to combine all .kupu XML
142: files to one large tree that can be fed to an XSLT processor.
143:
144: Overview:
145: ~~~~~~~~~
146:
147: =============================== ================================================
148: kupu/ (the root directory of the kupu distribution)
149: kupu/dist.kupu (kupu's default Distribution file)
150: kupu/default/ ('default' Implementation of Features)
151: kupu/default/feature1.kupu
152: kupu/default/feature2.kupu
153: kupu/default/wire.kupu (wires Parts to Slots)
154: kupu/default/include.kupu (imports all Features and the wiring from the
155: 'default' Implementation for convenience)
156: kupu/foo/ ('Foo' Implementation)
157: kupu/foo/feature1.kupu
158: kupu/foo/feature2.kupu
159: kupu/foo/wire.kupu ([re-]wires [additional] Parts to Slots)
160: kupu/foo/include.kupu (imports all Features and the wiring from the
161: 'default' Implementation for convenience)
162: kupu/foo/foo.py (some additional platform specific files)
163: kupu/foo/Foo.class
164: kupu/foo/fooicon.png
165: =============================== ================================================
166:
167: XML format
168: ----------
169:
170: ::
171:
172: <grammar xmlns="http://relaxng.org/ns/structure/1.0">
173:
174: <start>
175: <ref name="dist" />
176: </start>
177:
178: <define name="dist">
179: <element name="dist">
180: <interleave>
181: <ref name="featureOrInclude" />
182: <ref name="implementationOrder" />
183: <ref name="expand" />
184: </interleave>
185: </element>
186: </define>
187:
188: <define name="feature">
189: <element name="feature">
190: <attribute name="name">
191: <text />
192: </attribute>
193: <attribute name="implementation">
194: <text />
195: </attribute>
196: <element name="part">
197: <attribute name="name">
198: <text />
199: </attribute>
200: <ref name="partContents" />
201: <element>
202: </element>
203: </define>
204:
205: <define name="featureOrInclude">
206: <zeroOrMore>
207: <choice>
208: <!-- we can either include more features from elsewhere -->
209: <element name="include">
210: <ref name="featureOrInclude" />
211: </element>
212:
213: <!-- or provide actual features -->
214: <ref name="feature" />
215: </choice>
216: </zeroOrMore>
217: </define>
218:
219: <define name="wire">
220: <element name="wire">
221: <attribute name="implementation">
222: <text />
223: </attribute>
224: <zeroOrMore>
225: <ref name="fillSlot" />
226: </zeroOrMore>
227: </element>
228: </define>
229:
230: <define name="fillSlot">
231: <element name="fill-slot">
232: <attribute name="name">
233: <text />
234: </attribute>
235: <zeroOrMore>
236: <choice>
237: <ref name="arbitraryMarkup" />
238: <ref name="insertPart" />
239: </choice>
240: </zeroOrMore>
241: </element>
242: </define>
243:
244: <define name="expand">
245: <oneOrMore>
246: <element name="expand">
247: <zeroOrMore>
248: <ref name="defineSlot" />
249: </zeroOrMore>
250: </element>
251: </oneOrMore>
252: </define>
253:
254: <define name="defineSlot">
255: <element name="define-slot">
256: <attribute name="name">
257: <text />
258: </attribute>
259: </element>
260: </define>
261:
262: <define name="implementationOrder">
263: <element name="implementation-order>
264: <oneOrMore>
265: <element name="implementation">
266: <attribute name="name">
267: <text />
268: </attribute>
269: </element>
270: </oneOrMore>
271: </element>
272: </define>
273:
274: <define name="arbitraryMarkup">
275: <element name=""> <!-- XXX arbitrary markup -->
276: <ref name="partContents" />
277: </element>
278: </define>
279:
280: <define name="insertPart">
281: <element name="insert-part">
282: <attribute name="name">
283: <text />
284: </attribute>
285: <attribute name="part">
286: <text />
287: </attribute>
288: </element>
289: </define>
290:
291: <define name="partContents">
292: <zeroOrMore>
293: <choice>
294: <ref name="arbitraryMarkup" />
295: <ref name="defineSlot" />
296: </choice>
297: </zeroOrMore>
298: </define>
299:
300: </grammar>
301:
302:
303: Example markup:
304: ---------------
305:
306: dist.kupu
307: ~~~~~~~~~
308:
309: ::
310:
311: <kupu:dist
312: xmlns:kupu="http://kupu.oscom.org/namespaces/dist"
313: xmlns:xi="http://www.w3.org/2001/XInclude"
314: >
315:
316: <!-- Include implementations -->
317: <xi:include href="default/include.kupu" />
318: <xi:include href="zope2/include.kupu" />
319: <xi:include href="zope3/include.kupu" />
320: <xi:include href="silva/include.kupu" />
321: <xi:include href="plone/include.kupu" />
322: <xi:include href="apache-lenya/include.kupu" />
323: <xi:include href="roundup/include.kupu" />
324: <!-- ... -->
325:
326: <!-- Define the default slot to start with -->
327: <kupu:expand>
328: <kupu:define-slot name="start" />
329: </kupu:expand>
330:
331: <!-- Define an order for the implementations that are to be used. The
332: most specific one is located at the top, the last one should
333: always be 'default'. -->
334: <kupu:implementation-order>
335: <!-- most specific one at top -->
336: <kupu:implementation name="plone" />
337: <kupu:implementation name="default" />
338: </kupu:implementation-order>
339:
340: <!-- Plone does not want to use certain features -->
341: <kupu:disable-feature name="toolboxes" />
342: <kupu:disable-feature name="save" />
343: <kupu:disable-feature name="colorchooser" />
344:
345: </kupu:dist>
346:
347:
348: some_impl/include.kupu
349: ~~~~~~~~~~~~~~~~~~~~~~
350:
351: ::
352:
353: <kupu:include
354: xmlns:kupu="http://kupu.oscom.org/namespaces/dist"
355: xmlns:xi="http://www.w3.org/2001/XInclude"
356: >
357:
358: <!-- Include features -->
359: <xi:include href="feature1.kupu" />
360: <xi:include href="feature2.kupu" />
361:
362: </kupu:include>
363:
364: some_impl/feature1.kupu
365: ~~~~~~~~~~~~~~~~~~~~~~~
366:
367: ::
368:
369: <kupu:feature
370: name="feature1"
371: implementation="some_impl"
372: >
373:
374: <kupu:part name="part1">
375: <div>
376: <p>Part 1 of Feature 1</p>
377: </div>
378: </kupu:part>
379:
380: <kupu:part name="part2">
381: <p>
382:
383: This part defines a slot that can be filled with more markup by
384: other features:
385:
386: <div id="foobar">
387: <kupu:define-slot name="foobar" />
388: </div>
389:
390: </p>
391: </kupu:part>
392:
393: </kupu:feature>
394:
395: some_impl/wire.kupu
396: ~~~~~~~~~~~~~~~~~~~
397:
398: ::
399:
400: <kupu:wire
401: implementation="some_impl"
402: xmlns:kupu="http://kupu.oscom.org/namespaces/dist"
403: >
404:
405: <kupu:fill-slot name="foobar">
406: <kupu:insert-part feature="some_feature" part="some_part" />
407: <kupu:insert-part feature="another_feature" part="a_part" />
408: </kupu:fill-slot>
409:
410: </kupu:wire>
411:
412:
413: Questions/Problems
414: ==================
415:
416: - Yet to be solved: How to handle i18n in templates? Temporary
417: solution: use ZPT's i18n markup so that we have at least a declaration
418: of what is to be i18n'd.
419:
420:
421: Futures
422: =======
423:
424: - Feature/Part dependencies
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvs/cvsweb/icons/back.gif){kind=icon}
Return to TEMPLATE-SYSTEM.txt CVS log ![[TXT]](/cvs/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvs/cvsweb/icons/dir.gif){kind=icon}
Up to [Repository] / kupuMPIWG / doc