README

vCard plugin for Craft CMS 5.x

vCard generator plugin for Craft CMS 5

Requirements

This plugin requires Craft CMS 5.0.0 or later.

Installation

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

    cd /path/to/project
   

2. Then tell Composer to load the plugin:

    composer require nfourtythree/vcard
   

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for vCard.

vCard Overview

This plugin generates a link to download a vCard from data you specify

Configuring vCard

There is only one setting for this plugin which is salt this is a string used for salting the encoded data when generating the vCard link.

This can be set by creating a vcard.php config file in the config/ directory. Below is an example of the config file:

<?php

return [
    'salt' => 'your-salt-here'
];

Using vCard

The only thing that is really required is first name. Everything else is optional

Usage

There is a link variable available for usage in templates craft.vCard.link(options)

{% set options = {
  firstName: "Johnny",
  lastName: "Appleseed",
  additional: "Jim",
  prefix: "Mr",
  suffix: "Esq",
  company: "Apple Inc.",
  jobTitle: "Data Demo",
  email: [{ address: "johnny@apple.com", type: "WORK" }, "johnny@gmail.com"],
  url: "http://apple.com",
  phoneNumber: ["+1 234 567 89", { number: "+9 876 543 21"}],
  photo: "http://exmaple.com/images/avatar.jpg",
  address: [{
      name: "Apple",
      extended: "Suite 1",
      street: "1 Infinte Loop",
      city: "Cupertino",
      region: "CA",
      zip: "95014",
      country: "USA",
      type: "WORK;PARCEL;POSTAL"
    },
    {
      street: "1 Yemen Road",
      zip: "1234",
      country: "Yemen",
      type: "HOME;POSTAL"
    }],
  note: "Hi there",
  role: "Web Developer",
} %}

<a href="{{ craft.vCard.link(options) }}">Download my vCard</a>

Options

email

This can be specified as either a string johnny@apple.com or an array (or even a mix!)

  email: {
    address: "johnny@apple.com",
    type: "WORK"
  }

  // For multiple email addresses
  email: [{
      address: "johnny@apple.com",
      type: "WORK"
    },
    {
      address: "johnny@gmail.com",
      type: "PREF;HOME"
    }]

  // Mix and match example
  email: ["johnny@apple.com", {
      address: "johnny@gmail.com",
      type: "PREF;HOME"
    }]

url

This can be specified as either a string http://apple.com or an array (or even a mix!)

  url: {
    address: "http://apple.com",
    type: "WORK"
  }

  // For multiple urls
  url: [{
      address: "http://apple.com",
      type: "WORK"
    },
    {
      address: "http://google.com",
      type: "HOME"
    }]

  // Mix and match example
  url: ["http://apple.com", {
      address: "http://google.com",
      type: "HOME"
    }]

phoneNumber

This can be specified as either a string +1 234 567 89 or an array (or even a mix!)

  phoneNumber: {
    number: "+1 234 567 89",
    type: "PREF;WORK;VOICE"
  }

  // For multiple phoneNumbers
  phoneNumber: [{
      number: "+1 234 567 89",
      type: "WORK"
    },
    {
      number: "+9 876 543 21",
      type: "PREF;HOME"
    }]

  // Mix and match example
  phoneNumber: ["+1 234 567 89", {
      number: "+9 876 543 21",
      type: "HOME"
    }]

address

This can be either a single or multi array

  address: {
    name: "Apple",
    extended: "Suite 1",
    street: "1 Infinte Loop",
    city: "Cupertino",
    region: "CA",
    zip: "95014",
    country: "USA",
    type: "WORK;PARCEL;POSTAL"
  }

  // For multiple addresses
  address: [{
      name: "Apple",
      extended: "Suite 1",
      street: "1 Infinte Loop",
      city: "Cupertino",
      region: "CA",
      zip: "95014",
      country: "USA",
      type: "WORK;PARCEL;POSTAL"
    },
    {
      street: "1 Yemen Road",
      zip: "1234",
      country: "Yemen",
      type: "HOME;POSTAL"
    }]

ToDo

• Clean up / refactor code to tidy code that was done quickly

Brought to you by Nathaniel Hammond (nfourtythree)

Thanks to

• Jeroen Desloovere - https://github.com/jeroendesloovere/vcard
• nystudio107 - https://github.com/nystudio107/generator-craftplugin (for just making life easier / quicker)
• Chris Rowe - http://chrisrowe.net for the idea to make this plugin