Gravatar Quick Editor

Gravatar Quick Editor is a JavaScript library that allows users to integrate the Gravatar Quick Editor into their web applications, enabling easy editing of Gravatar profiles via a popup window. The library provides both a core class for advanced control and a simplified class for quick setup.

Features

• Simple integration with your web application.
• Core functionality for advanced usage.
• Simplified setup for quick integration.
• Supports real-time updates to avatar images using the PostMessage API.
• TypeScript support for type completion and validation.

Installation

Install with NPM or Yarn

Install the package using npm or yarn:

npm install @gravatar-com/quick-editor

yarn add @gravatar-com/quick-editor

Install with UNPKG

Import the library as shown below:

<!-- Import the library -->
<script src="https://unpkg.com/@gravatar-com/[email protected]" defer></script>

<script>
  // The library is accessible as a global variable
  console.log( Gravatar );
</script>

Replace x.x.x with the latest version number. Please refer to UNPKG's documentation for more information.

Usage

GravatarQuickEditor

The GravatarQuickEditor class simplifies the setup process by automatically setting up event handlers to open the popup and update avatar elements on the page.

Example

import { GravatarQuickEditor } from '@gravatar-com/quick-editor';

document.addEventListener( 'DOMContentLoaded', () => {
  new GravatarQuickEditor( {
    email: '[email protected]',
    editorTriggerSelector: '#edit-profile',
    avatarSelector: '#gravatar-avatar',
    scope: [ 'avatars' ],
  } );
} );

GravatarQuickEditorCore

The GravatarQuickEditorCore class provides advanced control over the Gravatar Quick Editor functionality, allowing developers to trigger popup events and set up profile update callbacks.

Core Example

import { GravatarQuickEditorCore } from '@gravatar-com/quick-editor';

document.addEventListener( 'DOMContentLoaded', () => {
  const quickEditorCore = new GravatarQuickEditorCore( {
    email: '[email protected]',
    scope: [ 'avatars', 'about' ],
    onProfileUpdated: () => {
      console.log( 'Profile updated!' );
    },
    onOpened: () => {
      console.log( 'Editor opened!' );
    },
  } );

  document.getElementById( 'edit-profile' ).addEventListener( 'click', () => {
    quickEditorCore.open();
  } );
} );

API

GravatarQuickEditor API

new GravatarQuickEditor(options: QuickEditorOptions);

QuickEditorOptions Type

type QuickEditorOptions = {
  email: string;
  editorTriggerSelector: string;
  avatarSelector?: string;
  scope?: Scope;
  locale?: string;
  avatarRefreshDelay?: number;
};

• email: string: The email address associated with the Gravatar profile. This is used to identify the profile to be edited.

• editorTriggerSelector: string: A CSS selector for the HTML element (e.g., button) that triggers the opening of the Gravatar Quick Editor popup.

• avatarSelector: string: A CSS selector for the HTML image element(s) that displays the Gravatar avatar. When the avatar is updated, the image(s) will be refreshed automatically.

• scope: Scope: An array specifying what sections of the profile can be edited in the popup. Check the list of valid scope values

• locale: string: The locale setting for the Gravatar editor interface. This can be used to set the language for the editor UI.

• avatarRefreshDelay: number: The delay in milliseconds before the avatar image is refreshed after an update. This can help ensure any cache can be busted before the new image is displayed.

While updating the avatar image, to bypass the browser's cache, the Quick Editor will add a t parameter with the current timestamp to the avatar URL.

GravatarQuickEditorCore API

new GravatarQuickEditorCore(options: QuickEditorCoreOptions);

QuickEditorCoreOptions Type

type QuickEditorCoreOptions = Partial< {
  email: string;
  scope: Scope;
  locale: string;
  onProfileUpdated: OnProfileUpdated;
  onOpened: OnOpened;
} >;

• email: string: The email address associated with the Gravatar profile. This is used to identify the profile to be edited.

• scope: Scope: An array specifying what sections of the profile can be edited in the popup. Check the list of valid scope values

• locale: string: The locale setting for the Gravatar editor interface. This can be used to set the language for the editor UI.

• onProfileUpdated: ( type: ProfileUpdatedType ) => void: A callback function that gets called when the profile is updated. This can be used to trigger additional actions in your application when the user saves changes to their profile. It will receive a parameter of type ProfileUpdatedType which can have one of the values: 'avatar_updated' | 'profile_updated'

• onOpened: () => void: A callback function that gets called when the editor popup is opened. This can be used for logging, analytics, or other actions when the popup is triggered.

Public functions

• open: ( email?: string ) => void: A function for triggering the Gravatar Quick Editor popup. It can receive an email address to identify the profile to be edited.

Valid Scope Values

• about
• avatars
• verified-accounts
• links
• interests
• contact-info
• wallet
• photos
• design
• privacy

Contribute to Gravatar Quick Editor

We welcome contributions to this project. Please follow the guidelines outlined in the CONTRIBUTING.md file.

License

Gravatar Hovercards is licensed under GNU General Public License v2 (or later).