Consolidated Avatar Template Package for Meteor
ANNOUNCEMENT
This package has been forked from @bengott's original Avatar package since it is longer maintained. It's been added to the utilities collection so that it can henceforth be maintained by other community members.
BREAKING CHANGES
In version 0.7.14 and earlier the Avatar options were overridden by assigning them directly to Avatar.options
. You should no longer do this. Instead, you must call Avatar.setOptions()
and pass the options that you wish to override.
The template parameters were overhauled in version 0.5.0. The Avatar.options
object changed quite a bit in version 0.6.0 too. And make sure you note the defaultType
/fallbackType
changes in version 0.7.0. Basically, things are still in a state of flux (pre-1.0.0), so check for breaking changes and read the rest of the README carefully when you update the package.
Installation
In your Meteor project directory, run:
$ meteor add utilities:avatar
Of course, you also need to add the accounts- packages for the services you're using (e.g. accounts-twitter) and accounts-ui or something similar in order to add login functionality to your app.
Usage
In an HTML file:
In a React component:
<Avatar (user=<user> || userId=<userId>)
(size="large" || "small" || "extra-small" || <user-defined size>)
(shape="rounded" || "circle")
(class="some custom classes")
(initials="<initials>") (bgColor="<color>") (txtColor="<color>") />
That may look like a lot of options, but they are all optional. Most of the time, your HTML will look more like this:
Optional template parameters:
user
oruserId
: Either a user object or userId string, default avatar if omittedsize
: Size of the avatar, by default either "large" (80px), "small" (30px), or "extra-small" (20px), although these may be overridden and new ones defined. If no size is provided 50px is used.shape
: Used for CSS border-radius property, either "rounded" or "circle", square if omittedclass
: Any custom CSS classes you'd like to define on the avatar container. The string is passed straight through to theclass
attribute on thediv
container element.initials
: Specify the initials to show for the initials avatar. The package automatically tries to determine the user's initials from profile data, but if defined, this param will override that.bgColor
andtxtColor
: Override the default colors for the initials avatar (color name or hex value string).
Global Configuration Options
The package exports a global Avatar
object which has a property named options
(also an object). The default options provided can be overridden by calling Avatar.setOptions()
and passing in the options that you wish to override.
Note that Avatar.setOptions()
must be called in both server and client code.
fallbackType
: Determines the type of fallback to use when no image can be found via linked services (Gravatar included):- "default image" (the default option, which will show either the image specified by defaultImageUrl, the package's default image, or a Gravatar default image). OR
- "initials" (show the user's initials)
defaultImageUrl
: This will replace the included package default image URL ("packages/avatar/default.png"). It can be a relative path (e.g. "images/defaultAvatar.png").gravatarDefault
: Gravatar default option to use (overrides defaultImageUrl option and included package default image URL). Options are available here.emailHashProperty
: This property on the user object will be used for retrieving gravatars (useful when user emails are not published).customImageProperty
: If you're storing images URLs in a property on the user object, you can specify it here.cssClassPrefix
: This property is used to prefix the CSS classes of the DOM elements generated by this package.imageSizes
: This property defines the avatar sizes that are available to your projectbackgroundColor
: The background color for initials avatars (color name or hex value string). The default is gray ("#AAA"
).textColor
: The text color for initials avatars (color name or hex value string). The default is white ("#FFF"
).
Example usage:
- To show initials when no avatar image can be found via linked services:
Avatar.setOptions({
fallbackType: "initials"
});
- To show the included package default image, you don't need to specify any options because this is the default functionality. However, you could specify it explicitly like so:
Avatar.setOptions({
fallbackType: "default image"
});
- To show a custom default image:
Avatar.setOptions({
defaultImageUrl: "img/default-avatar.png" OR "http://example.com/default-avatar.png"
});
Note that Gravatar's default option requires a publicly accessible URL, so it won't work when your app is running on localhost and you're using either the included package default image or a custom defaultImageUrl that is a relative path. It will work fine once deployed though.
- To show one of Gravatar's default options (e.g. "identicon"):
Avatar.setOptions({
gravatarDefault: "identicon"
});
Note that gravatarDefault overrides defaultImageUrl and the included package default image.
- Set a value to the
cssClassPrefix
to avoid conflicts in CSS class names. Setting the property value like this:
Avatar.setOptions({
cssClassPrefix: 'foo'
});
Will assign CSS class names prefixed by 'foo', like below:
<div class="foo foo-small foo-circle">
<img class="foo-image" src="path_to_your_avatar" alt="avatar" onerror="this.style.display='none';" width="30" height="30">
<span class="foo-initials">A</span>
</div>
If a cssClassPrefix
is not set, then the default prefix 'avatar' is used for CSS class names in the rendered the HTML:
<div class="avatar avatar-small avatar-circle">
<img class="avatar-image" src="path_to_your_avatar" alt="avatar" onerror="this.style.display='none';" width="30" height="30">
<span class="avatar-initials">A</span>
</div>
- If your app does not publish the user.emails object/property but publishes an email hash property instead, you can specify it like this (the Gravatar package generates a hash internally when you give it an email too; this just allows you to decouple those two steps so as not to make all your users' emails public):
Avatar.setOptions({
emailHashProperty: "email_hash"
});
Note that you can use Avatar.hash("address@email.com");
to generate a Gravatar email hash.
- You may override the default avatar sizes, or create new ones, by overriding the
imageSizes
option:
Avatar.setOptions({
imageSizes: {
'large': 80,
'mySize': 40
}
});
How the package chooses an avatar
Given a user object or userId string, Avatar will retrieve the user's image with the following priority:
- The user object's custom image URL (stored in the property defined by
Avatar.options.customImageProperty
) - GitHub
- Gravatar, which will try to return an avatar matching the user's email address/hash. If it can't find one, then:
- If
Avatar.options.fallbackType
is "initials", Gravatar returns a 404 (Not Found) response. - Else,- If
Avatar.options.gravatarDefault
is valid, Gravatar will return a default image (e.g. an identicon). - If
Avatar.options.gravatarDefault
is invalid or undefined, Gravatar will return either the image referenced byAvatar.options.defaultImageUrl
or the included default image.
- If
- If no image can be retrieved, the user's initials will be shown.
Required Fields/Properties on the User Object
Since fields in user.services
contain security info, it's often wise to restrict access to those in publications, e.g.:
UsersCollection.find({ /* query */ }, {
fields: {
//...
"services.facebook.id" : true
//...
}
});
Fields used to get avatar image (one per service):
"services.twitter.profile_image_url_https"
"services.facebook.id"
"services.google.picture"
"services.github.username"
"services.instagram.profile_picture"
"services.linkedin.pictureUrl"
Fields used to form initials (if needed):
"profile.firstName"
"profile.lastName"
"profile.familyName"
"profile.secondName"
"profile.name"
Linked Services/Accounts: By default, the Meteor accounts system creates a separate user account for each service you login with. In order to merge those accounts together, you'd need to use a package like accounts-meld or link-accounts. In the future, the plan is to add UI to allow the user to select which avatar they want to use and/or upload their own image.
Credits
- Sacha Greif, for suggesting the idea on crater.io
- Shai Alon, for contributing the Gravatar functionality to Telescope that I later modified
- Jérémie Parker, for providing the gravatar package
- Everyone who has contributed to this project. :)