Giter Site home page Giter Site logo

enesser / vcards-js Goto Github PK

View Code? Open in Web Editor NEW
416.0 15.0 155.0 78 KB

Create vCards to import contacts into Outlook, iOS, Mac OS, and Android devices from your website or application.

License: MIT License

JavaScript 100.00%
vcard javascript vcards-js outlook android ios react react-native

vcards-js's Introduction

vCards JS

Build Status

Create vCards to import contacts into Outlook, iOS, Mac OS, and Android devices from your website or application.

Screenshot

Install

npm install vcards-js --save

Usage

Below is a simple example of how to create a basic vCard and how to save it to a file, or view its contents from the console.

Basic vCard

var vCardsJS = require('vcards-js');

//create a new vCard
var vCard = vCardsJS();

//set properties
vCard.firstName = 'Eric';
vCard.middleName = 'J';
vCard.lastName = 'Nesser';
vCard.organization = 'ACME Corporation';
vCard.photo.attachFromUrl('https://avatars2.githubusercontent.com/u/5659221?v=3&s=460', 'JPEG');
vCard.workPhone = '312-555-1212';
vCard.birthday = new Date(1985, 0, 1);
vCard.title = 'Software Developer';
vCard.url = 'https://github.com/enesser';
vCard.note = 'Notes on Eric';

//save to file
vCard.saveToFile('./eric-nesser.vcf');

//get as formatted string
console.log(vCard.getFormattedString());

On the Web

You can use vCards JS on your website. Below is an example of how to get it working on Express 4.

var express = require('express');
var router = express.Router();

module.exports = function (app) {
  app.use('/', router);
};

router.get('/', function (req, res, next) {

    var vCardsJS = require('vcards-js');

    //create a new vCard
    var vCard = vCardsJS();

    //set properties
    vCard.firstName = 'Eric';
    vCard.middleName = 'J';
    vCard.lastName = 'Nesser';
    vCard.organization = 'ACME Corporation';

    //set content-type and disposition including desired filename
    res.set('Content-Type', 'text/vcard; name="enesser.vcf"');
    res.set('Content-Disposition', 'inline; filename="enesser.vcf"');

    //send the response
    res.send(vCard.getFormattedString());
});

Embedding Images

You can embed images in the photo or logo field instead of linking to them from a URL using base64 encoding.

//can be Windows or Linux/Unix path structures, and JPEG, PNG, GIF formats
vCard.photo.embedFromFile('/path/to/file.png');
vCard.logo.embedFromFile('/path/to/file.png');
//can also embed images via base-64 encoded strings
vCard.photo.embedFromString('iVBORw0KGgoAAAANSUhEUgAAA2...', 'image/png');
vCard.logo.embedFromString('iVBORw0KGgoAAAANSUhEUgAAA2...', 'image/png');

Date Reference

MDN reference on how to use the Date object for birthday and anniversary can be found at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date.

Complete Example

The following shows a vCard with everything filled out.

var vCardJS = require('vcards-js');

//create a new vCard
var vCard = vCardsJS();

//set basic properties shown before
vCard.firstName = 'Eric';
vCard.middleName = 'J';
vCard.lastName = 'Nesser';
vCard.uid = '69531f4a-c34d-4a1e-8922-bd38a9476a53';
vCard.organization = 'ACME Corporation';

//link to image
vCard.photo.attachFromUrl('https://avatars2.githubusercontent.com/u/5659221?v=3&s=460', 'JPEG');

//or embed image
vCard.photo.attachFromUrl('/path/to/file.jpeg');

vCard.workPhone = '312-555-1212';
vCard.birthday = new Date(1985, 0, 1);
vCard.title = 'Software Developer';
vCard.url = 'https://github.com/enesser';
vCard.workUrl = 'https://acme-corporation/enesser';
vCard.note = 'Notes on Eric';

//set other vitals
vCard.nickname = 'Scarface';
vCard.namePrefix = 'Mr.';
vCard.nameSuffix = 'JR';
vCard.gender = 'M';
vCard.anniversary = new Date(2004, 0, 1);
vCard.role = 'Software Development';

//set other phone numbers
vCard.homePhone = '312-555-1313';
vCard.cellPhone = '312-555-1414';
vCard.pagerPhone = '312-555-1515';

//set fax/facsimile numbers
vCard.homeFax = '312-555-1616';
vCard.workFax = '312-555-1717';

//set email addresses
vCard.email = '[email protected]';
vCard.workEmail = '[email protected]';

//set logo of organization or personal logo (also supports embedding, see above)
vCard.logo.attachFromUrl('https://avatars2.githubusercontent.com/u/5659221?v=3&s=460', 'JPEG');

//set URL where the vCard can be found
vCard.source = 'http://mywebpage/myvcard.vcf';

//set address information
vCard.homeAddress.label = 'Home Address';
vCard.homeAddress.street = '123 Main Street';
vCard.homeAddress.city = 'Chicago';
vCard.homeAddress.stateProvince = 'IL';
vCard.homeAddress.postalCode = '12345';
vCard.homeAddress.countryRegion = 'United States of America';

vCard.workAddress.label = 'Work Address';
vCard.workAddress.street = '123 Corporate Loop\nSuite 500';
vCard.workAddress.city = 'Los Angeles';
vCard.workAddress.stateProvince = 'CA';
vCard.workAddress.postalCode = '54321';
vCard.workAddress.countryRegion = 'United States of America';

//set social media URLs
vCard.socialUrls['facebook'] = 'https://...';
vCard.socialUrls['linkedIn'] = 'https://...';
vCard.socialUrls['twitter'] = 'https://...';
vCard.socialUrls['flickr'] = 'https://...';
vCard.socialUrls['custom'] = 'https://...';

//you can also embed photos from files instead of attaching via URL
vCard.photo.embedFromFile('photo.jpg');
vCard.logo.embedFromFile('logo.jpg');

vCard.version = '3.0'; //can also support 2.1 and 4.0, certain versions only support certain fields

//save to file
vCard.saveToFile('./eric-nesser.vcf');

//get as formatted string
console.log(vCard.getFormattedString());

Multiple Email, Fax, & Phone Examples

email, otherEmail, cellPhone, pagerPhone, homePhone, workPhone, homeFax, workFax, otherPhone all support multiple entries in an array format.

Examples are provided below:

var vCardsJS = require('vcards-js');

//create a new vCard
var vCard = vCardsJS();

//multiple email entry
vCard.email = [
    '[email protected]',
    '[email protected]',
    '[email protected]'
];

//multiple cellphone
vCard.cellPhone = [
    '312-555-1414',
    '312-555-1415',
    '312-555-1416'
];

Apple AddressBook Extensions

You can mark as a contact as an organization with the following Apple AddressBook extension property:

    var vCardsJS = require('vcards-js');
    var vCard = vCardsJS();
    vCard.isOrganization = true;

React Native

A React Native version exists here at this repository -- https://github.com/idxbroker/vCards-js/tree/react-native

Testing

You can run the vCard unit tests via npm:

npm test

Contributions

Contributions are always welcome!

Additional thanks to --

Donations

BTC 18N1g2o1b9u2jNPbSpGHhV6x5xs6Qou3EV

License

Copyright (c) 2014-2019 Eric J Nesser MIT

vcards-js's People

Contributors

bramzor avatar c-h- avatar enesser avatar jimmytsao avatar jkrenge avatar josias-r avatar mplno avatar randystevens avatar saibotrellum avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

vcards-js's Issues

Raw Base 64 format

Hello,

Thanks for an awesome library. I want to let you know my observations and improvement.

Can you add a method to add raw base64 format to the library.

embedFromData : function(data,mediaType){
this.mediaType = mediaType;
this.url = data;
this.base64 = true;
}

vCard.photo.embedFromData( raw data, 'PNG');

vCard on ios

it seems I can't add to contacts, do you know why ? Thanks.

ios format

Hi,
Some of the ios mobiles doesn't support the package parser format.
What is the correct format for ios?
Thanks ;)✨✨✨

Birthday in examples gives invalid date

First, thank you for the work, it really helps so keep it up =D.
I have found though that when using the example in the readme, the birthday date is not valid for javascript. Just update new Date('01-01-1985') to new Date(1985, 1, 1) =D

tests.js:5: Uncaught ReferenceError: require is not defined

Hi. Thanks for your plugin! But when i clone it. In my for folder, it hasn't any example.
I created index.html and implement tests.js into it. But it appeared a error.
Can you show how to use your plugin?
Sorry because i am a beginner.
Thanks for you support!
:D

Charset support for accent

I'm using your lib for a french application and I need support for accent.
After some tests, it seems that adding the charset in the vcard solve my pb.
Do you think it is possible to add the charset support in your lib to able to display accents as described in the following sample:

BEGIN:VCARD
VERSION:4.0
FN:frédéric
N;CHARSET=utf-8;:;pêché;;;
X-SOCIALPROFILE;CHARSET=utf-8;TYPE=twitter:http://www.twitter.com/frédéric
X-SOCIALPROFILE;TYPE=skype:S12345
REV:2015-05-18T21:43:30+00:00
END:VCARD

Empty LABEL param breaks vcard import in Thunderbird

Empty value of LABEL parameter (v4 format) should not be outputted in getFormattedAddress function otherwise it completely breaks import of vcard file in Thunderbird address book.
Importing is fine if LABEL contains some text. But empty values should not be outputted anyway.

Don't use new Array()

If somebody (me) stores e.g. the cellPhone as a number, it will crash the whole formatter.
(https://github.com/enesser/vCards-js/blob/master/lib/vCardFormatter.js#L223) as it means you're trying to generate an array with a certain size which can lead to errors if the range is too large.

E.g. new Array(12345678900) will throw following error:

RangeError: Invalid array length
    at Object.getFormattedString (/Project/node_modules/vcards-js/lib/vCardFormatter.js:254:39)
    at Object.getFormattedString (/Project/node_modules/vcards-js/index.js:321:35)
    ...

So vCard.cellPhone = new Array(vCard.cellPhone); should be replaced with vCard.cellPhone = [vCard.cellPhone];

X-SOCIALPROFILE problem

Hi first of all thank you for sharing this package with the community.

I had a problem when I tried to import a vCard with a X-SOCIALPROFILE into macOSX address book. The Mac app was not able to understand the encoding, please see the imported result:
Bildschirmfoto 2019-10-20 um 11 46 33

Removing the encodingPrefix did the trick (line 378) - however I am not sure if this is conform to the vCard standard.
formattedVCardString += 'X-SOCIALPROFILE' + ';TYPE=' + key + ':' + e(vCard.socialUrls[key]) + nl();

Could you please look into this problem?

Cheers,
Michael

Custom urls and uploading

Can we add custom urls similar to how we add custom socials? Something like vcard.url[custom] = 'http://mycustomurl.com'.
From what I can tell the only options right now are url and work url and in my scenario url is used by their website and 'work' is not the appropriate title or category for the additional url i want to add. Also, what if we had 3 urls?

Usage in vue/nuxt

I get this error

fs.writeFileSync is not a function. The problem is that fs is empty off course, but is there any solution? I now use browserify-fs for it

image

vCard 2.1 Addresses Formatted Incorrectly

We have an odd scenario where we need to support vCard 2.1, however, we've discovered a formatting issue with it on newer phones. In cases where we specify format 2.1, the label for the address shows as CHARSET. Upon further investigation, I discovered you format the ADR field exactly the same for 2.1 as you do for 3.0. This is making the phones pickup the label as the defined charset and not the type as specified or ignoring the field all together.

It took some digging, but I did find the original 2.1 specification with an example:

Delivery Addressing Properties
Delivery Address
This property specifies a structured representation of the physical delivery address for the vCard object. The property is made up of components that are based on the X.500 Post Office Box attribute, the X.520 Street Address geographical attribute, the X.520 Locality Name geographical attribute, the X.520 State or Province Name geographical attribute, the X.520 Postal Code attribute, and the X.520 Country Name geographical attribute.
This property is identified by the property name ADR. The property value consists of components of the address specified as positional fields separated by the Field Delimiter character (ASCII decimal 59). The property value is a concatenation of the Post Office Address (first field) Extended Address (second field), Street (third field), Locality (fourth field), Region (fifth field), Postal Code (six field), and Country (seventh field) strings. An example of this property follows:
ADR;DOM;HOME:P.O. Box 101;Suite 101;123 Main Street;Any Town;CA;91921-1234;
Support for this property is optional for vCard Writers conforming to this specification.
Delivery Address Type
This property parameter specifies the sub-types of physical delivery that is associated with the delivery address. For example, the label may need to be differentiated for Home, Work, Parcel, Postal, Domestic, and International physical delivery. One or more sub-types can be specified for a given delivery address.
The property parameter can have one or more of the following values:
Description
Property Parameter Value
TYPE=
Indicates a domestic address
DOM
Indicates an international address (Default)
INTL
Indicates a postal delivery address (Default)
POSTAL
Indicates a parcel delivery address (Default)
PARCEL
Indicates a home delivery address
HOME
Indicates a work delivery address (Default)
WORK

While it does say that you can specify TYPE=, modern Android and iPhones do not seem to pick up on this. The few examples I've found across the internet have also favored the type as the second field for ADR and omits the TYPE=

Contact not imported on Samsung devices when Base64 embedded image present

Hi,
When you embed a base64 string image using
vCard.photo.embedFromString('iVBORw0KGgoAAAANSUhEUgAAA2...', 'image/png'); the card cannot be imported on Samsung devices. I tried on different Samsung devices. It shows "Unable to load data".

The card imports correclty on iOS devices and on Windows computers.

When I modify the VCF file manually by adding an additional \r\n at the end of the base64 string, it can be imported correctly on Samsung devices and others.

Could you please have a look?

Best regards
Julien

NOT WORKING ON SAMSUNG DEVICES

BEGIN:VCARD
VERSION:3.0
FN;CHARSET=UTF-8:TestJulien TestBarbé
N;CHARSET=UTF-8:TestBarbé;TestJulien;;;
EMAIL;CHARSET=UTF-8;type=WORK,INTERNET:[email protected]
PHOTO;ENCODING=b;TYPE=image/jpeg:/9j/4AAQSkZJRgABAgAAZABkAAD/7AA [...] 9xHwt2bpyq6k+nuI0rh6aIpJ9JE13UVM6B1elBof//Z
TEL;TYPE=CELL:+3223473912
ADR;CHARSET=UTF-8;TYPE=WORK:;;Rue Neuve 1;;;;
ORG;CHARSET=UTF-8:TestPepper IT
REV:2021-05-02T21:03:37.622Z
END:VCARD

WORKING ON ALL DEVICES (mind the \r\n after the base 64 string)

BEGIN:VCARD
VERSION:3.0
FN;CHARSET=UTF-8:TestJulien TestBarbé
N;CHARSET=UTF-8:TestBarbé;TestJulien;;;
EMAIL;CHARSET=UTF-8;type=WORK,INTERNET:[email protected]
PHOTO;ENCODING=b;TYPE=image/jpeg:/9j/4AAQSkZJRgABAgAAZABkAAD/7AA [...] 9xHwt2bpyq6k+nuI0rh6aIpJ9JE13UVM6B1elBof//Z

TEL;TYPE=CELL:+3223473912
ADR;CHARSET=UTF-8;TYPE=WORK:;;Rue Neuve 1;;;;
ORG;CHARSET=UTF-8:TestPepper IT
REV:2021-05-02T21:03:37.622Z
END:VCARD

require $$ 0 svelte

Hello I am trying to implement the library with svelte but I get the error:
Uncaught ReferenceError: require $$ 0 is not defined
at
could you help me ?

Embed object using base64 string?

Is it possible to embed an image using a base64 string. Basically I'm allowing users to take pictures using their mobile device or built in laptop camera, which returns a string.

Social links aren't showing after vcard downloaded

Actually I am facing the problem regarding the social links after downloading the vcard file just because it's not showing the social links in my vcard after download.
Here is the code:
var vCardsJS = require('vcards-js');
//create a new vCard
var vCard = vCardsJS();

//set properties
vCard.firstName = name;
vCard.organization = companyName;
vCard.workPhone = phone;
vCard.url = website;
vCard.workEmail = email;
vCard.socialUrls['facebook'] = facebook;
vCard.socialUrls['instagram'] = instagram;
vCard.socialUrls['twitter'] = twitter;
vCard.socialUrls['youtube'] = youtube;
vCard.socialUrls['snapchat'] = snapchat;
vCard.socialUrls['tiktok'] = tiktok;
vCard.socialUrls['whatsapp'] = whatsapp;
vCard.socialUrls['pinterest'] = pinterest;
let card = await vCard.getFormattedString();
Links are coming from my site front-end.

Using in Angular (Typescript)

I'm trying to use the library in the Angular 8 application. For that I installed the package using npm and in the component file, I used

import * as vCardsJS from 'vcards-js';

myMethod() {
  const vCard = vCardsJS();
  ...
}

But this gives error message as

ERROR in ./node_modules/vcards-js/index.js
Module not found: Error: Can't resolve 'fs' in '/home/code/node_modules/vcards-js'

New property for WORK URL

A new property for URL;TYPE=WORK would be helpful since the current untyped URL vCard property is mainly used for personal website and not the business/work website.
It would also solve the problem when someone wants to have both personal and work websites included in a vcard.
New 'workUrl' object property could be introduced for this but it's just my suggestion.

How can i create one Vcard using many Json objects?

I can create one Vcard(vcf file) from one object.
But I want to create one Vcard(vcf file) from multiple objects.
e.g :
I have 3 Json objects such as
[ { N: 'Stenerson,Derik',
FN: 'Derik Stenerson',
ORG: 'Microsoft Corporation',
TITLE: '',
PHOTO: { TYPE: '', PHOTO: '' },
TEL: [ [Object], [Object] ],
ADR: [],
EMAIL: '[email protected]' },
{ N: 'Ganguly,Anik',
FN: 'Anik Ganguly',
ORG: ' Open Text Inc.',
TITLE: '',
PHOTO: { TYPE: '', PHOTO: '' },
TEL: [ [Object] ],
ADR: [],
EMAIL: '[email protected]' },
{ N: 'Moskowitz,Robert',
FN: 'Robert Moskowitz',
ORG: '',
TITLE: '',
PHOTO: { TYPE: '', PHOTO: '' },
TEL: [],
ADR: [],
EMAIL: '[email protected]' } ]

and want to create one Vcard such as Xyz.vcf then how to create it ?

Thanks in advance

Can't resolve 'fs' - React

Hi, what should I do to fix this error?? (usage for react.js)

Error Message:

ERROR in ./node_modules/vcards-js/index.js 37:17-30
Module not found: Error: Can't resolve 'fs' in '..\node_modules\vcards-js'
node   v16.15.0
npm    v8.13.2
yarn   v1.22.19

Logo is not rendered in output

There is a small typo in vCardFormatter.js in the condition for logo property that prevents to render it in output file.

Missing X-ABADR

iOS adds the country code as field X-ABADR to an address.

Sanitize when read vcard

HI,

i'm reading some files from outlook and i had to make some changes to work, see if that makes sense to incorporate some how

          let ediFileContent = fs.readFileSync(fileFound).toString();
          ediFileContent = ediFileContent.replace('begin:vcard', 'BEGIN:VCARD')
            .replace('end:vcard', 'END:VCARD');
          ediFileContent = ediFileContent.split('\n').map(p => {
            const arr = p.split(':');
            arr[0] = arr[0].toUpperCase().replace(';CHARSET=UTF-8', '');
            return arr.join(':');
          }).join('\n');

This is the original vcf:


begin:vcard
version:3.0
prodid:Microsoft-MacOutlook/f.17.0.160611
UID:D35EB00C-0C8E-4781-8E9C-372B0E2957D1
fn;charset=utf-8:Joao Mendes
n;charset=utf-8:Mendes;Joao;;;
title;charset=utf-8:Pré-venda
note;charset=utf-8:Grup.\n\n\n\n\n\n\n\n\n
tel;charset=utf-8;type=cell:99999-1326
end:vcard 

Add React Native Compatibility

Some developers are wanting to use this for React Native: https://stackoverflow.com/questions/38644405/react-native-using-a-javascript-module-that-relies-on-node-js-core-module/39236621#39236621
I created a separate branch with React Native compatibility from my fork of this repo.
You can either create a new branch with my changes or update the original repo to check the environment and load in react-native-fs if react native: https://github.com/idxbroker/vCards-js/tree/react-native

create vcard file with more than 4000 contacts with image

how to create .vcf file with more than 4000 contacts with images, I already created .vcf file with 4000 contacts using vcards-js but, the image does not display in contact profile in mobile, image display less than 10 contacts in .vcf file. it does not work more than 10 contacts. I want images in contact profile in .vcf file with more than 4000 contacts.

Phone in version 4 is not showed correctly

I am trying example from documentation:

https://www.npmjs.com/package/vcards-js#complete-example but with version 4.

`
var vCard = vCardsJS();

vCard.version = '4'
//set basic properties shown before
vCard.firstName = 'Eric';
vCard.middleName = 'J';
vCard.lastName = 'Nesser';
vCard.uid = '69531f4a-c34d-4a1e-8922-bd38a9476a53';
vCard.organization = 'ACME Corporation';

vCard.workPhone = '312-555-1212';

`
In version 4, the phone output:

TEL;VALUE=uri;TYPE="voice,work":tel:312-555-1212
Which is not showed correctly

Screen Shot 2022-04-10 at 14 07 55

When i use version 3, the output is TEL;TYPE=WORK,VOICE:312-555-1212 and it works as expected

Screen Shot 2022-04-10 at 14 10 31

Am i doing something wrong or how can i use phone in version 4?

Thanks

question: custom fields

I don't see any reference to setting custom field (X-FOO-BAR: something). Is there a way to do this that I'm missing?

tia,
dan

Parse VCard to JSON

Is there a way using this library to convert existing vcards back to objects, arrays and / or JSON?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.