Za'atar Digital

eServices for the rest of us

User Tools

Site Tools


gravatarurl:docs:zdgravatarurl

zdGravatarURL

This documentation contains excerpts of text from the Gravatar.com website.

Type Class
Super class Object

Properties


EmailAddress

Syntax
EmailAddress As String

Every Gravatar member is identified by his/her email address. This property should contain the member's address for which you want to retrieve the avatar.

// Simple use of zdGravatarURL
Dim theAvatar As New zdGravatarURL
theAvatar.EmailAddress = "example@domain.com"

// load the image in the HTMLViewer
HTMLViewer1.LoadPage theAvatar.AvatarURL
Important: The member's email address never appears in the URL generated by zdGravatarURL. A MD5 128-bits hash calculated from the specific email address requested is used to identify the Gravatar member's account.

DefaultImage

Syntax
DefaultImage As String

If the MD5 hash isn't recognized, then the server sends a default picture. If you prefer, you can use your own customized pictures as a default pictures by passing its URL as a string to the DefaultImage property. There are a few conditions which must be met for default image URL:

  • Must be publicly available. It cannot be on an intranet, behind HTTP Auth or a firewall.
  • Must be accessible via the HTTP or HTTPS protocol on the standard ports, 80 and/or 443.
  • Must have a recognizable image extension (jpg, jpeg, gif, png)
  • Must not include a query string. If it does, it will be ignored

Default images are passed through a security scan to avoid malicious content.

// Use of a custom default avatar URL
Dim theAvatar As New zdGravatarURL
theAvatar.EmailAddress = "example@domain.com"

// Set the default picture URL
theAvatar.DefaultImage = "http://www.mywebsite.com/images/mydefaultavatar.png"

// Display the avatar in an HTMLViewer
HTMLViewer1.LoadPage theAvatar.AvatarURL

The Gravatar API also provides a set of predefined default avatars. Some of them can vary depending on the hash.

Default Gravatar constants

Avatar Constant Value Description
kDefaultGravatar An empty string This is the generic image returned by Gravatar.
kDefaultMisteryMan “mm” A simple cartoon-style silhouetted outline of a person. Does not vary by email hash.
kDefaultIdentIcon “identicon” A geometric pattern based on an email hash.
kDefaultMonsterID “monsterid” A generated 'monster' with different colors, faces, etc…
kDefaultWavatar “wavatar” Generated faces with different backgrounds and features.
kDefaultRetro “retro” Awesome generated, 8-bits arcade-style pixelated faces.
kDefaultBlank “blank” A transparent PNG image.
  kDefault404 “404” Do not load any image if none is associated with the email hash. Instead return an HTTP 404 (file not found) response.

To access this set of pictures you can use the constants described in the table after the code example.

// Using one of the Gravatar default image
Dim theAvatar As New zdGravatarURL
theAvatar.EmailAddress = "example@domain.com"

// We choose the mystery man avatar
theAvatar.DefaultImage = zdGravatarURL.kDefaultMisteryMan

// Display the avatar in an HTMLViewer
HTMLViewer1.LoadPage theAvatar.AvatarURL

ForceDefault

Syntax
ForceDefault As Boolean

If this property is set to True, it will make Gravatar serve your application with the default image as set in the DefaultImage property.

// Use of ForceDefault
Dim theAvatar As New zdGravatarURL
theAvatar.EmailAddress = "example@domain.com"
theAvatar.DefaultImage = zdGravatarURL.kDefaultWavatar

#if DebugBuild Then
  // Force the use of the default avatar when running in debug mode.
  theAvatar.ForceDefault = True
#endif

HTMLViewer1.LoadPage theAvatar.AvatarURL

Rating

Syntax
Rating As String

Gravatar allows members to self-rate their images so that they can indicate if an image is appropriate for a certain audience. By default, only 'G' rated images are displayed unless you set the Rating property to a higher level. zdGravatarURL implements 4 constants to set the level of rating you want. If there is no pictures matching this rating level, then Gravatar will search for an image with a lower level of rating. If there no image available, then Gravatar will return the default image as set with the DefaultImage property.

Default Rating constants

Rating Constant Value Description Sends back
G kRatingG “g” Suitable for all audience G
PG kRatingPG “pg” Rude gestures, provocatively dressed individuals, the lesser swear words, mild violence. PG, G
R kRatingR “r” Harsh profanity, intense violence,nudity, hard drug use. R, PG, G
X kRatingX “x” Hardcore sexual imagery, extremely disturbing violence. X, R, PG, G

Size

Syntax
Size As Integer

By default, the pictures served by Gravatar are scaled to 80×80 pixels. If you want another size, you can set this property to this size within the 1 to 2048 pixels range.

Note that avatars are always square.

If you want to go back to the default size, use zdGravatarURL.kSizeDefault constant.

// Using the Size property
Dim theAvatar As New zdGravatarURL
theAvatar.EmailAddress = "example@domain.com"

// We need a 256 x 256 pixels image
theAvatar.Size = 256

HTMLViewer1.LoadPage theAvatar.AvatarURL

UseSSL

Syntax
UseSSL As Boolean

If your are serving pages over SSL ( i.e. using the 'https:' prefix ), then you want to serve your avatar over SSL too to avoid annoying browser warnings. For this purpose, set this property to True.

Shared Methods


VersionString

Introduced in v1.1

Syntax
VersionString() As String

Return the version of the zdGravatarURL class. The version 1.1 of zdGravatarURL will return the string “1.1”.

Methods


EmailAddressHash

Introduced in v1.1

Syntax
EmailAddressHash(inEmailAddress As String = “”) As String

It returns the hash for the passed email address. If inEmailAdress is empty it returns the hash for the content of the EmailAddress property.

URL

Syntax
URL() As String

Return a properly formatted URL given all the settings of the instance of the zdGravatarURL class. Use this URL in your application when you want to retrieve the Gravatar of your user.

//-- Simple use of zdGravatarURL

// Create a new instance of zdGravatarURL
Dim theAvatar As New zdGravatarURL

// Set the user email address
theAvatar.EmailAddress = "example@domain.com"

// Build the Gravatar URL and display the avatar in a HTMLViewer
HTMLViewer1.LoadPage theAvatar.AvatarURL

URL

Syntax
URL( inEmailAddress As String ) As String

Return a properly formatted URL given all the settings of the instance of the zdGravatarURL class, except for the EmailAddress property. The email address passed to the function is used to generate the hash used to identify the Gravatar member's account.

Calling this function doesn't change the EmailAddress property's content.

The code example below shows how to create an array of Gravatar URLs from an array of email addresses and with the same settings.

Function BuildURLsArray(inAddresses() As String) As String()

  //-- Return an array of Gravatar URLs generated from an array of addresses.
  // Note that the EmailAddress property is not used here.

  // Instantiate and setup a zdGravatarURL
  Dim theAvatar As New zdGravatarURL
  theAvatar.DefaultImage = zdGravatarURL.kDefaultIconMonsterID
  theAvatar.Rating = zdGravatarURL.kRatingPG
  theAvatar.Size = 128

  // Creating an array of URLs of the same size
  Dim theLastIndex As Integer = inAddresses.Ubound
  Dim theURLs() As String
  Redim theURLs( theLastIndex )

  // Loop through all provided addresses
  For i As Integer = 0 To theLastIndex
    // Generate the i-th URL
    theURLs( i ) = theAvatar.URL( inAddresses( i ) )
  Next

  // Return the result
  Return theURLs

End Function
gravatarurl/docs/zdgravatarurl.txt · Last modified: 2016/02/11 12:59 (external edit)