-
Notifications
You must be signed in to change notification settings - Fork 92
hCard
vCard data can be embedded inside an HTML document using the hCard format. hCards loosely adhere to version 3.0 of the vCard specification.
Below is an example of an hCard. The HTML document must contain a <link>
element which references the hCard profile. hCards rely heavily on class
attributes to identify which parts of the HTML document contain vCard data.
<html>
<head>
<link rel="profile" href="http://microformats.org/profile/hcard" />
</head>
<body>
<div class="vcard">
<h1 class="fn n">
<span class="prefix">Mr</span>.
<span class="given-name">John</span>
<span class="family-name">Doe</span>
</h1>
Email:
<a class="email" href="mailto:jdoe@example.com">
<span class="value">jdoe@example.com</span>
(<span class="type">home</span>)
</a>
<p class="note">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at lacus justo. Phasellus quis nisl eget augue gravida tempor in at ante. Suspendisse suscipit eleifend molestie.
</p>
</div>
</body>
</html>
The HCardParser
class handles the extraction of vCard data from an HTML document. Unlike most of the other reader classes in ez-vcard, this class is not streaming. The entire HTML DOM must be read into memory before the vCards can be extracted.
readNext()
Parses and returns the next VCard
object from the HTML document. The method returns null
when no more vCards can be found.
getWarnings()
Returns any problems the parser encountered while parsing the VCard
object that was last returned by readNext()
. Examples of things that could cause warnings are: unparseable property values (such as malformed date values).
Please see the Javadocs for a complete listing of all the methods.
The example below outputs the names and birthdays of each hCard found on a company's "staff" page.
URL url = new URL("http://company.com/staff");
HCardParser parser = new HCardParser(url);
try {
VCard vcard;
DateFormat df = new SimpleDateFormat("MM/dd/yyyy");
while ((vcard = parser.readNext()) != null) {
FormattedName fn = vcard.getFormattedName();
String name = (fn == null) ? null : fn.getValue();
Birthday bday = vcard.getBirthday();
Date date = (bday == null) ? null : bday.getDate();
String birthday = (date == null) ? null : df.format(date);
System.out.println(name + " " + birthday);
}
} finally {
parser.close();
}
If a property's value cannot be parsed (for example, due to a malformed date value), the property is treated as an extended property and a warning is logged. The extended property's value will contain the property's entire HTML element in string form. The code below demonstrates this:
String html =
"<html>" +
"<head>" +
"<link rel=\"profile\" href=\"http://microformats.org/profile/hcard\" />" +
"</head>" +
"<body>" +
"<div class=\"vcard\">" +
"Last modified: <span class=\"rev\">I don't know, like, 2 days ago?</span>" +
"</div>" +
"</body>" +
"</html>";
HCardParser parser = new HCardParser(html);
VCard vcard = parser.readNext();
parser.close();
List<String> warnings = parser.getWarnings();
System.out.println("Warnings: " + warnings);
System.out.println("REV property: " + vcard.getRevision());
RawProperty prop = vcard.getExtendedProperty("REV");
System.out.println("Extended property: " + prop.getValue());
The above code produces the following output:
Warnings: [rev property: Property value could not be parsed. It will be saved as an extended property instead.
Reason: Could not parse date string.
HTML: <span class="rev">I don't know, like, 2 days ago?</span>]
REV property: null
Extended property: <span class="rev">I don't know, like, 2 days ago?</span>
If your application does not require hCard parsing functionality, you can exclude the "jsoup" dependency from your build.
<dependency>
<groupId>com.googlecode.ez-vcard</groupId>
<artifactId>ez-vcard</artifactId>
<version>...</version>
<exclusions>
<!-- hCard parsing not needed -->
<exclusion>
<groupId>org.jsoup</groupId>
<artifactId>jsoup</artifactId>
</exclusion>
</exclusions>
</dependency>
hCards are very tightly intertwined with the HTML code of a webpage. Due to this fact, it's difficult to develop a general purpose hCard "writer" that can be used for any given webpage. The HCardPage
class creates an HTML page which serves as an example of what a vCard looks like when embedded in HTML. Feel free to use its Freemarker template file as a starting point for learning how to embed a vCard inside an HTML document.
add()
Adds a VCard
to the HTML page.
write()
Creates an HTML page that contains the contents of the VCard
s that were passed into the add()
method.
Please see the Javadocs for a complete listing of all the methods.
The example below writes a list of VCard
objects to an HTML file.
List<VCard> vcards = ...
HCardPage page = new HCardPage();
for (VCard vcard : vcards) {
page.add(vcard);
}
File file = new File("vcards.html");
page.write(file);
If your application does not require the use of the HCardPage
class, you can exclude the "freemarker" dependency from your build.
<dependency>
<groupId>com.googlecode.ez-vcard</groupId>
<artifactId>ez-vcard</artifactId>
<version>...</version>
<exclusions>
<!-- hCard writing not needed -->
<exclusion>
<groupId>org.freemarker</groupId>
<artifactId>freemarker</artifactId>
</exclusion>
</exclusions>
</dependency>
ez-vcard is maintained by Michael Angstadt
Table of Contents
Getting started
Examples
FAQ
Javadocs
Downloads
1 An Overview of the vCard data format
2 Reading and Writing vCard data with ez-vcard
2.1 Plain-text (traditional)
2.2 XML-encoded (xCard)
2.3 JSON-encoded (jCard)
2.4 HTML-encoded (hCard)
3 Differences between the vCard versions
4 Dealing with Non-standard Data
4.1 Working with non-standard properties and parameters
4.2 Property scribe
5 Project Information
5.1 News
5.2 Dependencies
5.3 Supported Specifications
5.4 Changelog
6 Reference
6.1 vCard Property Reference
6.2 Javadocs