Class | Vcard::Vcard::Maker |
In: |
lib/vcard/vcard.rb
|
Parent: | Object |
A class to make and make changes to vCards.
It can be used to create completely new vCards using Vcard#make2.
Its is also yielded from Vcard::Vcard#make, in which case it allows a kind of transactional approach to changing vCards, so their values can be validated after any changes have been made.
Examples:
Make a vCard.
Yields maker, a Vcard::Vcard::Maker which allows fields to be added to card, and returns card, a Vcard::Vcard.
If card is nil or not provided a new Vcard::Vcard is created and the fields are added to it.
Defaults:
Add an email field, EMAIL. email is a Vcard::Vcard::Email.
The block is optional, its only necessary if you want to specify the optional attributes.
Add an instant-messaging/point of presence address field, IMPP. The address is a URL, with the syntax depending on the protocol.
Attributes of IMPP are:
All attributes are optional, and so is the block.
The URL syntaxes for the messaging schemes is fairly complicated, so I don‘t try and build the URLs here, maybe in the future. This forces the user to know the URL for their own address, hopefully not too much of a burden.
IMPP is defined in draft-jennings-impp-vcard-04.txt. It refers to the URI scheme of a number of messaging protocols, but doesn‘t give references to all of them:
Add a photo field, PHOTO.
Attributes of PHOTO are:
or a non-registered image format (usually these start with an x-)
An error will be raised if neither image or link is set, or if both image and link is set.
Setting type is optional for a link image, because either the URL, the image file extension, or a HTTP Content-Type may specify the type. If it‘s not a link, setting type is mandatory, though it can be set to an empty string, ’’, if the type is unknown.
TODO - I‘m not sure about this API. I‘m thinking maybe it should be add_photo(image, type), and that I should detect when the image is a URL, and make type mandatory if it wasn‘t a URL.
Add a telephone field, TEL. tel is a Vcard::Vcard::Telephone.
The block is optional, its only necessary if you want to specify the optional attributes.
Add an X-AIM account name where xaim is an AIM screen name.
I don‘t know if this is conventional, or supported by anything other than AddressBook.app, but an example is:
X-AIM;type=HOME;type=pref:exampleaccount
Attributes of X-AIM are:
All attributes are optional, and so is the block.
Add a birthday field, BDAY.
birthday must be a time or date object.
Warning: It may confuse both humans and software if you add multiple birthdays.
Copy the fields from card into self using add_field. If a block is provided, each Field from card is yielded. The block should return a Field to add, or nil. The Field doesn‘t have to be the one yielded, allowing the field to be copied and modified (see Field#copy) before adding, or not added at all if the block yields nil.
The vCard fields BEGIN and END aren‘t copied, and VERSION, N, and FN are copied only if the card doesn‘t have them already.
Set the name fields, N and FN.
Attributes of name are:
name is a Vcard::Name.
All attributes are optional, though have all names be zero-length strings isn‘t really in the spirit of things. FN‘s value will be set to Vcard::Name#formatted if Vcard::Name#fullname isn‘t given a specific value.
Warning: This is the only mandatory field.