vcard proposal
[ikiwiki.git] / doc / todo / vCard_rendering.mdwn
1 Addressbooks are commonly kept on a CardDAV server, where the individual
2 contacts are represented as single vCard (`.vcf`) files. Supporting those files
3 as a source format could facilitate integration between ikiwiki and address
4 books, and allow linking wiki entries to people. With the plugin presented here
5 and the [[calypso|http://keithp.com/blogs/calypso/]] server, that is easily
6 possible.
7
8 The idea was first presented on [[forum/debconf13 ikiwiki bof|DebConf13]] by
9 [[chrysn]].
10
11 Software involved
12 =================
13
14 * CardDAV server
15
16   ikiwiki generates its pages from the local file system. Using the 
17   [[calypso|http://keithp.com/blogs/calypso/]] CardDAV/CalDAV server makes that
18   trivial, as it stores its contacts as plain files already (and under git
19   version control!).
20
21   The files can be pulled into ikiwiki in the form of an underlay.
22
23 * Rendering VCF files
24
25   A python plugin called `vcf` has been published in chrysn's plugin repository
26   at `git://prometheus.amsuess.com/ikiwiki-plugins`. It supports contact images
27   (as `data:` URLs) as well as all the attributes Evolution generates, creates
28   external hyperlinks for those attributes that can be dereferenced (including
29   telephone numbers), and renders vCard categories into ikiwiki tags.
30
31   Python was chosen as a programming language due to the availability of the
32   [[`vobject`|http://vobject.skyhouseconsulting.com/]] python module and the
33   author's personal preference.
34
35 * Linking to contacts
36
37   File names of vCard files are usually not usable
38   (`4FD53349-51280409-28AD50CB.vcf`). To make links like "`I've talked to
39   \[[John Doe]] about this`" possible, the [[todo/alias directive]] has to be
40   implemented in the same repository. (Work in progress.)
41
42 Issues / Further development
43 ============================
44
45 * The rendered output is currently a plain definition list, and could need some
46   theming and/or grouping.
47
48   The current implementation does not use templating, and instead generates
49   HTML directly in Python (with the help of the
50   [[MarkupSafe|https://pypi.python.org/pypi/MarkupSafe]] module). Due to the
51   [[limitations of the foreign language API|plugins/write/external]], ikiwiki's
52   regular templating can't be used anyway.
53
54 * Addresses are rendered by `python-vcard` builtin address renderer (plus a
55   hack to get unicode out of it), and are not always most beautiful; moreover,
56   this kind of rendering is not themable.
57
58 * The `paramlist` words in the vcards are plain dumped out after the respective
59   fields. That's unsuitable for theming, and would need localization.
60
61 * In general, the plugin is not internationalized.
62
63 * All VCF pages currently receive a 'Contact' tag. That needs configurability
64   and/or localization. In the same vein, prefix configuration for the category
65   taggings would be useful too.
66
67 * The alias plugin is not ready yet.
68
69 * vCards can not be edited. To be precise: vCards can be edited, but they show
70   vCard sources which are not suitable for user editing. Moreover, the changes
71   would be committed into the wiki main from the underlay, and not travel back.
72
73   Two approaches would make editing feasible, a relatively easy one and a
74   hard-but-wow-if-it-works one:
75
76   * Use a dedicated vCard editing online tool like CardDavMate, which accepts
77     URLs for editing (unlike CardDavMate). Ideally we would even hijack the
78     edit button on vCard pages to take the user to a proper editor.
79
80   * Have a simple edit mask for vCard objects. (It'd be ok if it was incomplete
81     with respect to fields, the vCard format is designed to make that
82     possible). That's related to the
83     [[forum/an alternative approach to structured data|structured data]] issue.
84
85     In such a setup, the vCard list would not go to an underlay, but rather to
86     a git checkout in a subdirectory or a submodule, from which the change
87     could then be pushed back to Calypso. (AFAIK, different git roots are not
88     supported in ikiwiki yet.)
89
90 * Would such a renderer be useful for vCalendar too? (vCard and vCalendar only
91   differ in what they can represent, not in how they do it.)
92
93 Status
94 ======
95
96 The setup is currently usable, but just barely so. Once the basic issues are
97 solved (aliases, parameters for tags, enhanced appearence), I will suggest this
98 plugin for inclusion in ikiwiki.
99
100 -- [[chrysn]]