Make YAML template configurable

[mxmehl]

When adding a new contact, the full template (from helpers.py#L263) is a bit too crowded for experienced users – I for myself don't need many of the fields.

Can we make this template configurable, either by a command line parameter or in khard.conf to use another plain yaml file? Right now the only way to edit this is by changing the helpers.py file before compilation which is not user-friendly.

[whnr]

For the time being, try this as a one liner in the terminal of your choice:

tmp=$(mktemp -t tmp-vcard-XXXXXX.yaml); cp short.yaml $tmp; vim $tmp; khard add -i $tmp; rm $tmp

I made an alias out of it.

My short.yaml looks like this:

First name : 
Last name  : 

Birthday : 

Organisation : 
Title : 

Phone :
    cell : 
    work : 
    home : 

Email :
    home : 
    work : 

Address :
    home :
        Extended : 
        Street   : 
        Code     : 
        City     : 
        Region   : 
        Country  : 

# notes
# for multi-line notes use:
#   Note : |
#       line one
#       line two
Note : 

[lucc]

I only gave my +1 above but forgot to say a bit more: I think it is a good idea. I would go with a config option (and maybe also a command line option additionally). The default value could be None which selects the old builtin template. Later we could also ship more templates, but that is of very low priority right now.

The only thing missing is that someone sends a pull request ;)

[lucc]

The corresponding code that we have right now is rather ugly. One part is in khard.helpers.get_new_contact_template() and the even uglier bit in khard.carddav_object.CarddavObject.get_template(). Maybe we can find way to use str.format() to interpolate a given vcard into a yaml template. That would enable us to reuse the technique for custom output format strings on the command line.

Maybe simple python format strings might be to limited to cope with all the special things we currently do in our yaml template. In this case we could check out a templating engine like jinja2, but I would be happier if we can do without that extra complexity (for the end user).

[lucc]

I have just moved the template string from helpers.py to a separate data file. We can now think about dropping more templates there and making them selectable and adding some other path (~/.config/khard/templates?) to the search path.

But there is one important thing we have to check with any new template and I have not yet investigated the corresponding code: Does loading of any custom / non default yaml template change the vcard in unintended ways?

To answer this question we need to define a behaviour for:

• what happens when a key is not present in the yaml input? -> leave the old value in the vcard or delete it?
• what happens when a key has an empty value? -> set the attribute to empty or delete it?
• how to explicitly delete a key?

Currently I think that explicitly setting a value to the empty string does not make sense in the vcard so we can use this to delete the key. That would mean we can leave missing keys untouched. @mxmehl @whnr what do you think? What do others think?

[mxmehl]

Thank you! I don't know how khard works internally and what the difference between empty and deleted keys is in CardDAV, so I cannot give useful input to your questions I'm afraid...

[whnr]

After consulting https://tools.ietf.org/html/rfc6350 I assume…

• Custom vCard fields. They should all be named something like X-foobar and it should be safe. see section 6.10
• missing fields: the minimal valid vCard should look like this, if I got the RFC right. These are the only mandatory fields. Everything else is optional

BEGIN:VCARD
FN:Foo Bar
VERSION:4.0
END:VCARD

[lucc]

@whnr yes I think that is correct (check test/fixtures/vcard/minimal.vcf for example :)

I am not so much concerned about syntactical correctness of the vcards we will write as we use a library for that (vobject). The point that bothers me are semantics of some border cases. Missing keys like mentioned above or the following scenario:

• let's assume we decided on one semantics above
• somebody has a template without an organisation
• they edit a contact and add an organisation: foo
• does this overwrite all the organisations in the vcard (which the user did not see during editing) or is it apended?

The problem here is that with the full yaml template we can be sure that the user did see all data from the vcard and we can effectively delete all the data in it and retrieve it from the edited yaml.

More generally speaking: We do need semantics for all possible partial transfers of data from vcard -> yaml -> vcard.

[lucc]

I opened #272 and #275 as prerequisites for this issue.

[lucc]

One simple solution to the editing problem where the user did not see but then organisations value but the give a new one could be to just ask the user what to do interactively.

[treeent]

New here… Great app 😊

I have read the documentation and this thread but I don’t understand how to use a custom template. It seems I need to use khard new -i <template-filename>. But I always get this error message:

Wrapping unversioned vCard object, setting version to 3.0.
Error: You must either enter a name or an organisation

(using Khard 0.19.1 on Manjaro)

[lucc]

@treeent one of your existing vcards in the address book has no version entry. Does your template file have a name or organisation field? You know that -i is for a yaml document with data not for the use case described in this issue. Compare https://khard.readthedocs.io/en/latest/commandline.html#create-contact

[treeent]

Not sure I understand. I need to say I’m no English-native, so it’s probably only a natural language misunderstanding. 😬 🙄 😳 If what I write is unclear, don’t hesitate to say so!

In my mind, a template is a generic file that needs to be customized/filled with specific data. For a yaml file, I’d say only the keys: (and # comments) but not the corresponding values. Something like what appears in the editor when I type khard new without any further options.

But, if I understand you correctly, the option -i expects an argument that’s a yaml file, already filled with one specific contact’s data. Did I understand correctly? 😬

[mxmehl]

But, if I understand you correctly, the option -i expects an argument that’s a yaml file, already filled with one specific contact’s data. Did I understand correctly? 😬

Yes, you understand correctly.

Use the alias provided in the first reply. In my fish shell, I set the following:

alias khardadd='set tmp (mktemp -t tmp-vcard-XXXXXX.yaml); cp -v ~/bin/khard-template.yaml $tmp; vim $tmp; khard add -i $tmp; rm $tmp'

This way, you can use khardadd which opens an editor, you can fill in the template, and upon save/close the editor, khard will import the file.

Still, this way is quite hacky, which is why this issue probably should remain open.

[treeent]

Thanks!