I wanted a simple method of adding vCard export capability from my FileMaker databases to get Contact information into my Contacts application. This is my first attempt at Modular FileMaker (as defined at modularfilemaker.org) although I do generally try to make my code as portable as possible.
Update 2014-10-23: I forgot to credit Donald Clark at FileMaker Pro Gurus for inspiring this quest to find an easy cross platform method of exporting vCards in the first place. Sometimes you start working on something and it takes so long to get it done that you forget why you started.
Update 2015-10-09: An even easier method of creating vCards that seem to work cross platform is demonstrated by Joe Simpson of Radical Application Development. He uses Base64Encode and then Base64Decode to generate the file in a container field. Then it is a simple matter to export it. Check it out here and see if it meets your needs. Might be even easier to implement than the Virtual List approach below.
Why is it so complicated?
This shouldn’t be as hard as I am making it, but in order to make the solution cross platform, it requires a little extra complexity.
In theory, you should just be able to concatenate all the required fields and text into a global field and then export the vCard text from that field using Export Field Contents.
Why use a Virtual List to Export this file?
The reason for using the Virtual List technique is because of UTF-8 text formatting issues, which I have discussed before. The script step ‘Export Field Contents’ generates a UTF-16 formatted text file, which some Calendar apps don’t see as valid. The ‘Export Records’ step has the option of generating a UTF-8 formatted text file, which Calendar apps accept.
After testing different formats on Mac and Windows, including UTF-8, it seems that the Windows ANSI format will work on both platforms.
How to Implement in Your Solution
The demo file is based on FileMaker’s built-in Contacts template.
To add this functionality to your solution, you will need to add:
- a data table called Virtual_List_Utility with two fields
- the scripts in the Export vCard folder
- an onscreen button called Export vCard
- add a UUID field if necessary to your Contacts data table
- edit the script with the Required Fields
These FileMaker components should be added in the order listed above. The scripts reference the data table and the button references the script.
Once the script is imported (copy and paste in FileMaker Pro Advanced), you will need to edit the Required Fields section of the script to match up with the particular fields of your own solution.
The vCard uses a UUID to identify duplicate records, so if you don’t already have a UUID field in your solution, you should add one at this point and use the “Replace’ command with Get(UUID) to make sure every existing record has a UUID before proceeding.
How it works
Click the Export vCard button.
Choose ‘Open’ or ‘Email’ from the dialog box
‘Open’ will export the vCard from FileMaker Pro and attempt to import it into your default Contacts application
Emailing a vCard
If you selected ‘Email’, your default email client should open with a vCard file attached and the Subject line filled in.
Opening a vCard
Contacts attempting to import the vCard file. If you have run this script before, the option ‘Review Duplicate’ may appear.
Implementing Export vCards in your solution
The README says the same things that are being documented here.
- Copy the Virtual_List_Utility data table into your solution. No additional relationships are required.
- Copy the Export vCards Folder of scripts and sub folders into your solution
- Edit the Configuration and Settings script called ‘Export vCard – Generate vCard Text – Set REQUIRED FIELDS‘
- The other scripts should just work without further modification.
- The ‘Export vCard – Main Script’ is the callable script, referenced by the Export vCard button.
- Copy the Export vCard button into your solution
Export vCard README
This ‘script’ is the documentation for the module.
Modifying ‘Export vCard – Generate vCard Text – Set REQUIRED FIELDS’ script
Edit the REQUIRED FIELDS to use the fields in your solution.
Required Fields – “Set Variable” Options
To edit a Required Field, double click on the variable and then click on the “Specify…” button.
Required Fields – Specify Calculation
In the Specify Calculation dialog,
- In the Calculation area, select just the field name
- Scroll through your Contacts fields to find the appropriate field to replace the one in use.
- Double click the desired field to have it replace the field in the calculation text.
- Click OK when done.
Export vCards – Layouts
Three layouts are included (or modified)
- Startup Screen – The developer’s hbase.net information
- Contact Details – the only modification is the addition of the vCard Export button
- Virtual_List_Utility – used in the export
It is not necessary to import any of these layouts into your solution. The Virtual_List_Utility layout will be created when you add the data table. It does not require any relationships to be created. You may want to turn off the visibility of this layout in your solution as it is not required for the user interface.
The only thing to paste into your solution is the Export vCard button from the Contacts Details layout.
Test the vCard Export
Run the Export or Email vCard script from the button.
If you get an error message when attempting to import the vCard into your address book, open the .vcf file in a text editor and review the text generated. First change the $Path variable in the Main Script to get(DesktopPath) so you can easily locate the file. Then open the file with a text editor such as TextMate and review. Things to look for:
- Extra carriage returns
- Check the file format
- Missing data
Remember to set the $Path variable back to Get(TemporaryPath) when you are done troubleshooting.
If you want to add more fields to your vCards Export, I recommend that you export a vCard from your chosen Contacts application, examine it with a text editor and then copy the format back to FileMaker, mirroring the approach taken in building the vCard in this solution. If you do something awesome, please send me a copy, and I will try to include it in an updated version of the demo file.
Known Issues – Windows – Notes field
I could not figure out a way to get the Windows Notes field to work with carriage returns. Substituting carriage returns with ‘\n’ works on a Mac, but not Windows.
Known Issues – Exporting/Importing Images
In theory, exporting images should work. In reality it doesn’t. If you have any ideas on this, let me know and I can continue to improve the demo file.
Update 2014-10-23: This is working now, thanks for John Renfrew’s feedback on Modular FileMaker. He suggested substituting the Carriage Returns with Line Feeds and presto-chango! — it works.
Substitute ( Base64Encode ( Contacts::Photo Container ) ; Char ( 13 ) & Char (10) ; “” )
The Substitute replaces the ASCII Character for a Return with a Line Feed.
- Line feed CHAR (10)
- Carriage return CHAR (13)