summaryrefslogtreecommitdiff
path: root/KEP-0012.txt
blob: 93de08191b55b6c592739e2575b5fc7989c65e14 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
{{kep
 |number=12
 |ticketnumber=
 |title=Color configuration storage for resources and categories
 |author=Georg Greve
 |author_email=greve@kolabsys.com
 |status=draft
 |type=design
 |creation_date=2011-08-26
 |obsoleted_by=
 |related=
}}


== Abstract ==
This Kolab Enhancement Proposal (KEP) <ref name="kep">[[KEP:1]] Bootstrapping the KEP process</ref> defines part of a changeset applied against Kolab XML version 1.0 of Kolab Format 2.0 for introduction of a new configuration and preference storage to be shared among clients for user defined color preferences for categories and resources such as calendars, address books or task lists. Based on KEP #9<ref name="kep9">[[KEP:9]] Storage of configuration and application control information</ref>, this KEP will make use of METADATA annotations as well as configuration XML objects and specialised folders for their storage.

== Update to the XML Format ==
The following changes to the Kolab Format are part of the changeset against Kolab XML version 1.0 as described by Kolab Format 2.0:

=== '/vendor/kolab/color' RFC 5464 folder annotation ===
Each folder '''MAY''' be annotated with an entry '/vendor/kolab/color' set to <color>, which is defined as follows:
* The annotation '''MAY''' be used in both 'private' and 'shared' namespace. When the annotation is set in both namespaces, 'private' '''SHALL''' be authoritative for display;
* Clients '''SHALL''' provide measures for selectively disabling the functionality in the 'private' or 'shared' namespace by disabling the annotation for either namespace, or both;
* The value of <color> '''SHALL''' be a sRGB<ref name="srgb">Wikipedia: [https://secure.wikimedia.org/wikipedia/en/wiki/SRGB sRGB]</ref> color value expressed in a 6-digit hexadecimal web color<ref name="webcolors">Wikipedia: [https://secure.wikimedia.org/wikipedia/en/wiki/Web_colors Web colors]</ref> with the magic value of 'XXXXXX' referring to an explicit 'No Color' selection;
* Where clients support the usage of colors for resources, they '''SHALL''' consider the value of '/vendor/kolab/color' annotation authoritative;
* Sub-folders '''SHALL''' inherit the <color> value of their parent folder. To break the inheritance chain a different color '''SHALL''' be specified or the magic value 'XXXXXX' '''SHALL''' be used for setting 'No Color';
* 'No Color' '''SHALL''' mean that the client is free to visualize these entries in the most neutral manner available based on its visualization context. By default, 'No Color' '''SHOULD''' be interpreted as transparency for backgrounds, and black for foregrounds, unless the clients' standard text color is something else;
* When the user sets the color for a folder and the user has sufficient permissions, clients '''MAY''' allow the user to choose whether to set the color for the 'private' or 'shared' namespace;
* Where the client does not present the user with an explicit selection in which namespace to store the selection, clients '''SHALL''' store the selection in the 'shared' namespace for all folders for which the user has admin permissions and use the 'private' namespace for all other folders;
* Where the user is not authorized to store color preferences in the 'shared' namespace, the client '''SHALL''' automatically fall back to the 'private' namespace;
* When '/vendor/kolab/color' is not set in a folder or any of its parent folders, clients '''MAY''' use their default colors/visualization schema, in which case they '''SHOULD''' store these preferences as appropriate by the rules defined above.

==== Disabling folder color functionality ====
Administrators of the Kolab servers '''MAY''' disable the '/vendor/kolab/color' RFC 5464 folder annotation in the IMAP server configuration for the 'private' or 'shared' namespace, or both. 

=== 'category' object configuration ===
==== Recital ====
Categories are freely user defined. Their hierarchy is expressed through the special character ':' which separates the parent category name from the sub-category. There is no limit to the nesting level. An object can have an unlimited number of categories, which are storied in the 'categories' field with comma-separation.

==== Object definition ====
Incorporating KEP #9<ref name="kep9"></ref>, this KEP defines a new XML 'configuration' object of type 'category' as follows:
* The 'X-Kolab-Type' {{rfc|2822}} <ref name="rfc2822">{{rfc|2822|title=Internet Message Format}}</ref> message header of the encapsulating email object '''SHALL''' be set to 'application/x-vnd.kolab.configuration.category';
* From the common fields, the object '''SHALL''' have all the required fields 'uid', 'creation-date', 'last-modification-date', and 'type';
* The 'type' field '''SHALL''' be set to 'category';
* The object '''SHALL''' also require at least one occurance of the specific field 'name' which '''MAY''' define a 'color' attribute;
* The field 'name' '''MAY''' occur multiple times in one object;
* Each 'name' field '''MAY''' have a nested hierarchy of sub-fields corresponding to the sub-categories which '''MAY''' each define separate 'color' attributes. Where no 'color' attribute is defined, the 'color' value is inherited from the parent;
* The value of the 'color' attribute '''SHALL''' be identical to the value of the '/vendor/kolab/color' annotation, above, a missing 'color' attribute in a 'category' object '''SHALL''' be treated as inheritance from the parent category, and the magic value 'XXXXXX' '''SHALL''' be an explicit 'No Color' definition;
* Objects of type 'category' '''MAY''' be stored in all non-email folders;
* If there are several 'category' objects defining the color for the same category or categories, the following rules '''SHALL''' apply:
** Where several 'category' objects define colors for the same category in one folder, the entry with the latest 'last-modification-date' shall prevail. A client '''MAY''' warn users of such conflicting settings and offer cleanup;
** Where several 'category' objects define colors for the same category in different folders within one hierarchy, sub-folders prevail over parent folders. A client '''MAY''' choose to warn users of such redefinition and offer cleanup;
** Where several 'category' objects define colors for the same category in different folders within separate hierarchies, the entry with the latest 'last-modification-date' of the prevailing entries of each hierarchical tree '''SHALL''' prevail.
* A sub-category that has no color assigned shall inherit its color from the parent category;
* A category that has no color assigned and has no parent category '''MAY''' either be visualized as 'No Color' '''-- OR --''' have its color assigned by the client, in which case the client '''SHOULD''' store this assignment in the users main 'configuration' folder.

==== Examples ====
The following examples constitute valid 'category' objects according to this KEP:

 <?xml version="1.1" encoding="UTF-8"?>
 <configuration version="2.1">
   <!-- Common fields -->
   <uid>lahb1625akx@some.host.somewhere</uid>
   <creation-date>2011-08-26T18:00:00Z</creation-date>
   <last-modification-date>2011-08-26T18:00:00Z</last-modification-date>
   <product-id>Superclient (tm)</product-id>
 
   <type>category</type>
   
   <name color="8A2BE2">Work</name>
 </configuration>

to define that the category 'Work' is visualized using 'BlueViolet', or

 <?xml version="1.1" encoding="UTF-8"?>
 <configuration version="2.1">
   <!-- Common fields -->
   <uid>anotherrandomstring@some.host.somewhere</uid>
   <creation-date>2011-08-11T12:18:06Z</creation-date>
   <last-modification-date>2011-08-11T12:18:06Z</last-modification-date>
   <product-id>Another Superclient (tm)</product-id>
 
   <type>category</type>
   
   <name color="DC143C">Work
    	  <name color="00008B">Meeting</name>
 	  <name color="008B8B">Telephone
 	        <name color="XXXXXX">ConfCall</name>
 	        </name>
     	  <name>Office</name>
 	  </name>
   <name color="8A2BE2">Play</name>
 </configuration>

to define that the category 'Work' is visualized using 'Crimson', as is 'Work:Office', while 'Work:Meeting' is visualized as 'DarkBlue', 'Work:Telephone' is visualized in 'DarkCyan' and 'Work:Telephone:ConfCall' has an explicit assignment of 'No Color'. And finally the category 'Play' is assigned 'BlueViolet'.

== Client behaviour ==
Microsoft maintains a mapping table for its color names to Web colors in the MSDN<ref name="mscolors">MSDN: [http://msdn.microsoft.com/en-us/library/aa358802%28v=VS.85%29.aspx Colors by Name]</ref>. This table '''SHALL''' be used by Outlook connectors to most closely represent the colors defined for the resource or category. 

Authors of other clients '''SHOULD''' default to the Microsoft color table<ref name="mscolors"></ref> to promote consistency across clients. Clients '''MAY''' allow custom color definitions and tables.

If a category is defined in a configuration object according to this KEP and this category is '''not''' currently assigned to any object in the users data set, clients '''SHOULD''' present it along with all other categories in the appropriate dialog(s) that are used to assign categories.
{{note|How to detect that folder colors have been disabled|When attempting to retrieve an annotation that is not defined for this namespace, RFC 5464 specifies a response 'BAD' for 'GETMETADATA'. It is recommended that clients request the value of the annotation for both namespaces by default (e.g. through 'GETMETADATA "INBOX" /private/vendor/kolab/color /shared/vendor/kolab/color') and then try to retrieve the annotation for each namespace individually to detect whether one of them is still available. This test can be done once and the result cached at least for the session.}}

== Upgrade Path ==
This KEP adds new functionality and folder types that will not be understood by older clients. 

It is therefore a breaking change that will be applied in a changeset with other disruptive changes.

== Rationale ==
=== Colors for all resources ===
Most groupware clients provide the means to color-code all types of groupware objects, including email (with flags), such as Outlook<ref name="outlook">How-To Geek: [http://www.howtogeek.com/howto/4693/color-code-outlook-for-easier-management/ Color Code Outlook for Easier Management]</ref>, but no client currently shares this information with other client (instances) through IMAP.

This is highly desirable as consistent use of colors across all clients will make usage more intuitive and users will no longer need to set the colors in each client individually. The same is true for an explicit 'No Color' setting<ref name="nocolor">Kolab Format posting by Shawn Walker: [http://kolab.org/pipermail/kolab-format/2011-May/001355.html Re:Pre-KEP Request for Input: Storage of categories & colors]</ref>.

=== Colors per folder ===
In Kolab, one folder always represents one resource, e.g. an address book, a calendar, a task list, so storing the color for that resource as a folder annotation allows to (a) have consistent colors on one resource across the entire installation, and (b) set a different color scheme for individual users. With inheritance, it is possible to color whole trees appropriately. Annotations seem the most efficient way of storing this information because they can be read without parsing the entire folder.

=== Colors per category ===
In addition, colors are also supported for categories, e.g. for sorting events in a calendar. These are transversally to the folder colors, and different clients have different approaches to visualisation, e.g. KDE Kontact allows to customize the display to any of the following:
* Category inside, calendar outside
* Calendar inside, category outside
* Only calendar
* Only category

KDE Kontact also allows nested levels of categories, making it necessary for this KEP to provide means of storage for them.

Categories are substantially more complex than resource colors because unlike for resources, which are tied to folders, any object of any resource type anywhere in the folder tree can define any number of categories simply by using them. Any of these categories can be re-used in any object of any resource type and closely match the concept of what is also often referred to as 'tags'<ref name="tag">Wikipedia: [https://secure.wikimedia.org/wikipedia/en/wiki/Tag_%28metadata%29 Tag (metadata)]</ref>. So a client can only know all user-defined categories after having parsed all objects within the entire IMAP tree of resources for a user, including all resources in the 'shared' and 'user' namespaces that this user has access to. 

This makes annotations an inferior choice to store this information, and even finding ways to make use of annotations for this purpose would not bring advantages because the client still has to parse the entire tree to know the complete set of categories.

Clients '''can''' however make use of the 'X-Kolab-Type' {{rfc|2822}} <ref name="rfc2822" /> message header by searching for the value 'application/x-vnd.kolab.configuration.category' to quickly identify all objects that contain categories and their color definitions, making retrieval of category objects more efficient than retrieval of category names/definitions.

So while more expensive in resource than the per folder coloring, the proposed approach for category coloring seems like the most efficient resolution of the requirement. Allowing storage in all non-email folders in particular allows addressing use cases where specific categories are defined in a shared folder with a specific coloring scheme that should be inherited by all clients that have access to the objects in this folder.

== References ==

{{Reflist}}

== Copyright ==

This document has been placed in the public domain.