vcard 0.1.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 86

vCard #

pub package

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

Install #

To use this package, add vcard as a dependency in your pubspec.yaml file like so.

dependencies:
  vcard: any

Then run the flutter tooling:

flutter packages get

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.

/// Import the package
import 'package:vcard/vcard.dart';

///Create a new vCard
var vCard = VCard();

///Set properties
vCard.firstName = 'FirstName';
vCard.middleName = 'MiddleName';
vCard.lastName = 'LastName';
vCard.organization = 'ActivSpaces Labs';
vCard.photo.attachFromUrl('/path/to/image/file.png', 'PNG');
vCard.workPhone = 'Work Phone Number';
vCard.birthday = DateTime.now();
vCard.title = 'Software Developer';
vCard.url = 'https://github.com/valerycolong';
vCard.note = 'Notes on contact';

/// Save to file
vCard.saveToFile('./contact.vcf');

/// Get as formatted string
print(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.

///import the package
import 'package:vcard/vcard.dart';

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

///set basic properties shown before
vCard.firstName = 'FirstName';
vCard.middleName = 'MiddleName';
vCard.lastName = 'Last Name';
vCard.uid = '6yuuhuhj-c34d-4a1e-8922-bd38a9476a53';
vCard.organization = 'ActivSpaces Labs';

///link to image
vCard.photo.attachFromUrl('/path/to/image/file.png', 'JPEG');

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

vCard.workPhone = '312-555-1212';
vCard.birthday = DateTime.now();
vCard.title = 'Software Developer';
vCard.url = 'https://github.com/valerycolong';
vCard.workUrl = 'https://activspaces.com';
vCard.note = 'Notes on contact';

///set other vitals
vCard.nickname = 'Scarface';
vCard.namePrefix = 'Mr.';
vCard.nameSuffix = 'JR';
vCard.gender = 'M';
vCard.anniversary = DateTime.now();
vCard.role = 'Software Development';

///set other phone numbers
vCard.homePhone = 'Home Phone';
vCard.cellPhone = 'Cell Phone';
vCard.pagerPhone = 'Pager Phone';

///set fax/facsimile numbers
vCard.homeFax = 'Home Fax';
vCard.workFax = 'Work Fax';

///set email addresses
vCard.email = 'labs@activspaces.com';
vCard.workEmail = 'hello@activspaces.com';

///set logo of organization or personal logo (also supports embedding, see above)
vCard.logo.attachFromUrl('https://www.activspaces.com/wp-content/uploads/2019/01/ActivSpaces-Logo_Dark.png', 'PNG');

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

///set address information
vCard.homeAddress.label = 'Home Address';
vCard.homeAddress.street = 'Great Soppo';
vCard.homeAddress.city = 'Buea';
vCard.homeAddress.stateProvince = 'SW';
vCard.homeAddress.postalCode = '00237';
vCard.homeAddress.countryRegion = 'Cameroon';
vCard.homeAddress.type = 'HOME';

vCard.workAddress.label = 'Work Address';
vCard.workAddress.street = 'Molyko';
vCard.workAddress.city = 'Buea';
vCard.workAddress.stateProvince = 'SW';
vCard.workAddress.postalCode = '00237';
vCard.workAddress.countryRegion = 'Cameroon';
vCard.workAddress.type = 'WORK';

///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('./contact/file.vcf');

///get as formatted string
print(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:


///import the package
import 'package:vcard/vcard.dart';


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

///multiple email entry
vCard.email = [
    'e.nesser@emailhost.tld',
    'e.nesser@emailhost2.tld',
    'e.nesser@emailhost3.tld'
];

///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 vCard = VCard();
    vCard.isOrganization = true;

Original Source #

This is a dart port of vCards-js package by Eric J Nesser https://github.com/enesser/vCards-js

Testing #

You can run the VCard unit tests via (WIP):

flutter test

Credits #

Contributions are always welcome!

Thanks to Eric whose original work made life so much easier for me.

Dependencies #

This package depends on:

Contributions #

Contributions are always welcome!

Work with us #

labs@activspaces.com

License #

Copyright (c)2019 ActivSpaces Labs MIT

0.1.0 #

  • Format changes on vcard.dart

0.0.9 #

  • Updated example README.md file.

0.0.8 #

  • Updated example README.md file.

0.0.7 #

  • Added example project to package.
  • Remove use of console.log in examples in favour or print.

0.0.6 #

  • Fixed minor formatting issues.

0.0.5 #

  • Updated the package description.

0.0.4 #

  • Minor changes with README.md file.

0.0.3 #

  • Minor changes with README.md file.

0.0.2 #

  • Added meta package dependency and small changes to README.md

0.0.1 #

  • Initial Open Source release.

example/README.md

vCard Example #

Demonstrates how to use the vCard package - a dart port of vCard JS by Eric J Nesser.

Getting Started #

For help getting started with this package from readme documentation.

Basic 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.

/// Import the package
import 'package:vcard/vcard.dart';

///Create a new vCard
var vCard = VCard();

///Set properties
vCard.firstName = 'FirstName';
vCard.middleName = 'MiddleName';
vCard.lastName = 'LastName';
vCard.organization = 'ActivSpaces Labs';
vCard.photo.attachFromUrl('/path/to/image/file.png', 'PNG');
vCard.workPhone = 'Work Phone Number';
vCard.birthday = DateTime.now();
vCard.title = 'Software Developer';
vCard.url = 'https://github.com/valerycolong';
vCard.note = 'Notes on contact';

/// Save to file
vCard.saveToFile('./contact.vcf');

/// Get as formatted string
print(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.

///import the package
import 'package:vcard/vcard.dart';

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

///set basic properties shown before
vCard.firstName = 'FirstName';
vCard.middleName = 'MiddleName';
vCard.lastName = 'Last Name';
vCard.uid = '6yuuhuhj-c34d-4a1e-8922-bd38a9476a53';
vCard.organization = 'ActivSpaces Labs';

///link to image
vCard.photo.attachFromUrl('/path/to/image/file.png', 'JPEG');

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

vCard.workPhone = '312-555-1212';
vCard.birthday = DateTime.now();
vCard.title = 'Software Developer';
vCard.url = 'https://github.com/valerycolong';
vCard.workUrl = 'https://activspaces.com';
vCard.note = 'Notes on contact';

///set other vitals
vCard.nickname = 'Scarface';
vCard.namePrefix = 'Mr.';
vCard.nameSuffix = 'JR';
vCard.gender = 'M';
vCard.anniversary = DateTime.now();
vCard.role = 'Software Development';

///set other phone numbers
vCard.homePhone = 'Home Phone';
vCard.cellPhone = 'Cell Phone';
vCard.pagerPhone = 'Pager Phone';

///set fax/facsimile numbers
vCard.homeFax = 'Home Fax';
vCard.workFax = 'Work Fax';

///set email addresses
vCard.email = 'labs@activspaces.com';
vCard.workEmail = 'hello@activspaces.com';

///set logo of organization or personal logo (also supports embedding, see above)
vCard.logo.attachFromUrl('https://www.activspaces.com/wp-content/uploads/2019/01/ActivSpaces-Logo_Dark.png', 'PNG');

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

///set address information
vCard.homeAddress.label = 'Home Address';
vCard.homeAddress.street = 'Great Soppo';
vCard.homeAddress.city = 'Buea';
vCard.homeAddress.stateProvince = 'SW';
vCard.homeAddress.postalCode = '00237';
vCard.homeAddress.countryRegion = 'Cameroon';
vCard.homeAddress.type = 'HOME';

vCard.workAddress.label = 'Work Address';
vCard.workAddress.street = 'Molyko';
vCard.workAddress.city = 'Buea';
vCard.workAddress.stateProvince = 'SW';
vCard.workAddress.postalCode = '00237';
vCard.workAddress.countryRegion = 'Cameroon';
vCard.workAddress.type = 'WORK';

///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('./contact/file.vcf');

///get as formatted string
print(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:


///import the package
import 'package:vcard/vcard.dart';


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

///multiple email entry
vCard.email = [
    'e.nesser@emailhost.tld',
    'e.nesser@emailhost2.tld',
    'e.nesser@emailhost3.tld'
];

///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 vCard = VCard();
    vCard.isOrganization = true;

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  vcard: ^0.1.0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:vcard/vcard.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
77
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
86
Learn more about scoring.

We analyzed this package on Oct 20, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21
  • Flutter: 1.9.1+hotfix.4

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Maintenance issues and suggestions

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (intl).

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
intl ^0.15.8 0.15.8 0.16.0
meta ^1.1.6 1.1.7
path ^1.6.2 1.6.4
path_provider ^1.1.0 1.3.1
validators ^2.0.0+1 2.0.0+1
Transitive dependencies
collection 1.14.11 1.14.12
platform 2.2.1
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test