Element: <oj-avatar>

Oracle® JavaScript Extension Toolkit (JET)
5.2.0
E97691-01

QuickNav

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Version:

5.2.0

Since:

4.0.0

Module:

ojavatar

JET Avatar

Description: Themeable, WAI-ARIA-compliant element that often represents a person.

A JET avatar is an icon capable of displaying a custom image, or initials, or a placeholder image. The order of precedence for what is displayed, in order from highest to lowest, is:

Custom image specified through the "src" attribute
Initials specified through the "initials" attribute
Default placeholder image

//Avatar with initials
<oj-avatar initials="AB">
</oj-avatar>

The application must set role and aria-label for accessibility purposes. JET Avatar does not have any interaction with the application, therefore it is not keyboard navigable by default. The aria-label will be picked up by the tabbable/focusable parent unless it is overriden by the application. The application can set a tooltip by setting the title attribute of the avatar.

In order to meet accessibility requirements for text, color contrast ratio between the background color and text must be greater than 4.5 for the two smallest avatars and 3.1 for the five larger avatars. Avatar's default background satisfies the 3.1 color contrast ratio. The background will automatically be darkened for the two smallest sizes to satisfy the more stringent 4.5 contrast ratio. If colors are customized through theming, the application is responsible for specifying colors that satisfy the 3.1 contrast ratio. The custom background color will be automatically darkened as well for the two smallest avatars.

The src attribute will display the image as a background-image. These images do not appear in high contrast mode. For this reason, initials must be specified and and will be shown instead.

Image

The avatar will display the image provided from the src attribute if the src attribute is populated. If the src attribute is not provided and the initials have been, the initials will be displayed. If neither src nor initials attributes are populated, a single person placeholder image is shown. Use the class oj-avatar-group-image to use the group placeholder image. Examples displaying each type of avatar:

//Individual Placeholder
<oj-avatar>
 </oj-avatar>
//Group Placeholder
<oj-avatar class="oj-avatar-group-image">
 </oj-avatar>
//Initials
<oj-avatar initials="AB">
</oj-avatar>
//Image
<oj-avatar initials="AB" src="image.jpg">
</oj-avatar>

Styling

The following CSS classes can be applied by the page author as needed.

Class	Description
oj-avatar-group-image	Use to diplay avatar group placeholder image instead of single person placeholder image.

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.

Attributes

initials :string

Specifies the initials of the avatar. Will only be displayed if the src attribute is null. Required if src attribute is provided for accessibility purposes. Will be displayed if the src attribute is not specified, or in high contrast mode for accessibility purposes.

Default Value:

null

Names

Item	Name
Property	`initials`
Property change event	`initialsChanged`
Property change listener attribute (must be of type function)	`on-initials-changed`

Examples

Renders a default medium avatar with initials

<oj-avatar initials='AB'></oj-avatar>

Get or set the initials property after initialization

//Get avatar initials
var initials = myAvatar.initials;

//Set initials property to 'NT'
myAvatar.initials = "NT";

size :string

Specifies the size of the avatar.

Supported Values:

Name	Type	Description
`"xxs"`	string	extra, extra small avatar
`"xs"`	string	extra small avatar
`"sm"`	string	small avatar
`"md"`	string	medium avatar, default value
`"lg"`	string	large avatar
`"xl"`	string	extra large avatar
`"xxl"`	string	extra, extra large avatar

Default Value:

"md"

Names

Item	Name
Property	`size`
Property change event	`sizeChanged`
Property change listener attribute (must be of type function)	`on-size-changed`

Examples

Renders avatar displaying default placeholder image with size attribute set to large

<oj-avatar size='lg'></oj-avatar>

Get or set the size property after initialization

//Get avatar size
var size = myAvatar.size;

//Set size property to xs
myAvatar.size = "xs";

src :string

Specifies the src for the image of the avatar. Image will be rendered as a background image. In high contrast mode, initials will be displayed instead since background images will not be rendered.

Default Value:

null

Names

Item	Name
Property	`src`
Property change event	`srcChanged`
Property change listener attribute (must be of type function)	`on-src-changed`

Examples

Renders a default medium avatar with a image

<oj-avatar src='image.jpg'></oj-avatar>

Get or set the src property after initialization

//Get avatar src
var src = myAvatar.src;

//Set src property to 'image2.jpg'
myAvatar.src = "image2.jpg";

Methods

getProperty(property) → {any}

Retrieves a value for a property or a single subproperty for complex properties.

Parameters:

Name	Type	Description
`property`	string	The property name to get. Supports dot notation for subproperty access.

Returns:

Type: any

Example

Get a single subproperty of a complex property:

var subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

setProperties(properties) → {void}

Performs a batch set of properties.

Parameters:

Name	Type	Description
`properties`	Object	An object containing the property and value pairs to set.

Returns:

Type: void

Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value) → {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.

Parameters:

Name	Type	Description
`property`	string	The property name to set. Supports dot notation for subproperty access.
`value`	any	The new value to set the property to.

Returns:

Type: void

Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");