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 [[DebConf13|forum/debconf13 ikiwiki bof]] 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     [[structured data|forum/an alternative approach to 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]]