Skip to content

Latest commit

 

History

History
195 lines (132 loc) · 13.9 KB

README.md

File metadata and controls

195 lines (132 loc) · 13.9 KB
Raw

adapt-contrib-hotgraphic

Hot Graphic is a presentation component bundled with the Adapt framework. Hot Graphic in action

When a learner clicks on a hot spot within the image, a pop-up is displayed that consists of text with an image. Visit the Hot Graphic wiki for more information about its functionality and for explanations of key properties.

In the standard configuration, the 'hot spots' are clickable 'pin' icons overlaying the main image - but it's possible to replace the default 'pin' icon with a custom image (see the _pin setting for more information) or, using the _useGraphicsAsPins setting, create a 'tiled layout' of images where each 'tile' acts as a hot spot.

By default, when the viewport size changes to the smallest range, this component will behave like a Narrative component. All information will remain available but formatted as a narrative rather than as hot spots on a graphic. This behaviour can be overridden by changing the _isNarrativeOnMobile setting to false.

Installation

As one of Adapt's core components, Hot Graphic is included with the installation of the Adapt framework and the installation of the Adapt authoring tool.

  • If Hot Graphic has been uninstalled from the Adapt framework, it may be reinstalled. With the Adapt CLI installed, run the following from the command line:

    adapt install adapt-contrib-hotgraphic

    Alternatively, this component can also be installed by adding the following line of code to the adapt.json file:

    "adapt-contrib-hotgraphic": "*"

    Then running the command:

    adapt install

    (This second method will reinstall all plug-ins listed in adapt.json.)

  • If Hot Graphic has been uninstalled from the Adapt authoring tool, it may be reinstalled using the Plug-in Manager.

Settings Overview

The attributes listed below are used in components.json to configure Hot Graphic, and are properly formatted as JSON in example.json. Visit the Hot Graphic wiki for more information about how they appear in the authoring tool.

Attributes

core model attributes: These are inherited by every Adapt component. Read more.

_component (string):

This must be set to: "hotgraphic".

_classes (string):

CSS class name(s) to be applied to this component's containing div. The class must be predefined in one of the Less files. Separate multiple classes with a space.

_layout (string):

This defines the horizontal position of the component in the block. Acceptable values are full, left or right.

instruction (string):

This optional text appears above the component. It is frequently used to guide the learner’s interaction with the component.

mobileBody (string):

This is optional text that will be substituted for body when device.screenSize is small (i.e. when viewed on mobile devices, except when the _isNarrativeOnMobile setting is set to false).

mobileInstruction (string):

This is optional text that will be substituted for instruction when device.screenSize is small (i.e. when viewed on mobile devices, except when the _isNarrativeOnMobile setting is set to false).

_isMobileTextBelowImage (boolean):

Like mobileBody and mobileInstruction, _isMobileTextBelowImage is only applicable when device.screenSize is small (i.e. when viewed on mobile devices, except when the _isNarrativeOnMobile setting is set to false). The default is false. When set to true, the replacement Narrative will not use the default "strapline" layout. Instead both the image and text of each stage remain visible, with the text positioned below the image.

_setCompletionOn (string):

Determines when Adapt will register this component as having been completed by the learner. Acceptable values are "allItems" and "inview". "allItems" requires each pop-up item to be visited. "inview" requires the Hot Graphic component to enter the view port completely.

_canCycleThroughPagination (boolean):

Enables the pop-ups to be cycled through endlessly using either the previous or next icon. When set to true, clicking "next" on the final stage will display the very first stage. When set to false, the final stage will display only a "previous" icon. The default is false.

_hidePagination (boolean):

When set to true, hides the "previous" and "next" icons and progress indicator (e.g., "1/5") on the pop-up's toolbar. The default is false.

_isNarrativeOnMobile (boolean):

When set to false the Hotgraphic will render a scaled down 'desktop' version (pins over image / tiles) of the component in mobile view instead of being replaced by a Narrative interaction. The default is true.

_isMobileTextBelowImage (boolean):

If enabled, on mobile, the text area drops below the image instead of being behind the strapline button. When using _isStackedOnMobile: true or _isNarrativeOnMobile: false, this attribute will be ignored. The default value is false

_isStackedOnMobile (boolean):

If enabled, on mobile, text and images will be stacked vertically. No interaction will be required to view all items as the user will simply scroll down. _isNarrativeOnMobile must be set to true. The default value is false

_useNumberedPins (boolean):

If set to true, the pin icons will be replaced with the item number. Useful if you want pins to be visited in a set order or show steps in a process. The default is false.

_useGraphicsAsPins (boolean):

If set to true, the image specified by _graphic.src will be ignored and the popup images specified in _items[n]._graphic.src will instead be laid out in a 2 column grid system. See example.json for a working example. The default is false.

_hasStaticTooltips (boolean):

If set to true, tooltips (if enabled) will always be shown rather than only on hover.

_isRound (boolean):

If set to true, the popup images will inherit a 50% border radius. Ideal for use with images that are square that are required to be round. The default is false.

_pinOffsetOrigin (boolean):

If set to true, the pins origin point will be changed from top left to center. This option will enable the pin to remain stationary when viewing responsively. The default is false.

_tooltip (object):

_isEnabled (boolean):

When set to true the tooltip will be shown on hover over the item. When _hasStaticTooltips is set to true, the tooltip will always be shown. The default is false.

text (string):

The tooltip text to display for the item.

_position (string):

The tooltip position in relation to the pin. Can be any combination of top, left, right, and bottom (e.g. top left or bottom). The default is bottom.

_classes (string):

CSS class name(s) to be applied to the pin tooltip. The class must be predefined in one of the Less files. Separate multiple classes with a space.

_graphic (object):

The graphic object that defines the image over which the hot spots are rendered (except when the _useGraphicsAsPins setting is enabled). It contains the following settings:

src (string):

File name (including path) of the image. Path should be relative to the src folder (e.g. "course/en/images/origami-menu-two.jpg").

alt (string):

The alternative text for this image. Assign alt text to images that convey course content only.

attribution (string):

Optional text to be displayed as an attribution. By default it is displayed below the image. Adjust positioning by modifying CSS. Text can contain HTML tags, e.g., Copyright © 2015 by <b>Lukasz 'Severiaan' Grela</b>.

_items (array):

Multiple items may be created. Each entry in the array should be an object, containing the following settings:

_top (number):

Each item must contain _top and _left coordinates to define its position over the main graphic. Enter a percentage value (0-100) that this item should be from the top border of the main graphic. Not required for tile/grid layout.

_left (number):

Enter a percentage value (0-100) that this item should be from the left border of the main graphic. Not required for tile/grid layout.

title (string):

This is the title text for the hot spot's pop-up.

body (string):

This is the main text for a hot spot pop-up.

strapline (string):

This text is displayed when device.screenSize is small (i.e. when viewed on mobile devices, except when the _isNarrativeOnMobile setting is set to false). It is presented in a title bar above the image.

_imageAlignment (string):

Defines the alignment of the item image in the pop up. The default alignment is right. Not required for tile/grid layout.

  • "left": Image aligned to the left of the text area
  • "top": Image aligned above the text area
  • "right": Image aligned to the right of the text area
  • "bottom": Image aligned below the text area

_classes (string):

CSS class name(s) to be applied to the popup item. Classes available by default are:

  • "hide-desktop-image": Hides the pop up image in desktop view
  • "hide-popup-image": Hides the pop up image for all screen sizes

Any other classes need to be predefined in one of the Less files. Separate multiple classes with a space.

_graphic (object):

The image that is associated with this item - which will be displayed in a popup when the pin is selected by the learner (although note that the _useGraphicsAsPins setting allows for it to be used as a 'tile' in the main image instead). It contains the following settings:

src (string):

File name (including path) of the image. Path should be relative to the src folder (e.g. "course/en/images/origami-menu-two.jpg").

alt (string):

The alternative text for this image. Assign alt text to images that convey course content only.

attribution (string):

Optional text to be displayed as an attribution. By default it is displayed below the image. Adjust positioning by modifying CSS. Text can contain HTML tags, e.g., Copyright © 2015 by <b>Lukasz 'Severiaan' Grela</b>.

_classes (string):

CSS class name(s) to be applied to hotgraphic pin or, alternatively, to the hotspot tile when _useGraphicsAsPins is set to true. The class must be predefined in one of the Less files. Separate multiple classes with a space.

_pin (object):

Optional image that can appear instead of the default pin icon. See example.json for a working example. It contains the following settings:

src (string):

File name (including path) of the image. Path should be relative to the src folder (e.g. "course/en/images/origami-menu-two.jpg").

alt (string):

The alternative text for this image. Assign alt text to images that convey course content only.

Accessibility

Hot Graphic has been assigned a descriptive label using the aria-label attribute: ariaRegion.

Other descriptive labels are used to provide context of the previous, current and next item. The following attributes are used to provide this functionality: item, previous and next.

These labels are not visible elements. They are utilized by assistive technology (such as screen readers). Should any of these labels need to be customised or translated, they can be found within the globals object in properties.schema (or Project settings > Globals in the Adapt Authoring Tool).

adapt learning logo Author / maintainer: Adapt Core Team with contributors
Accessibility support: WAI AA
RTL support: Yes
Cross-platform coverage: Chrome, Chrome for Android, Firefox (ESR + latest version), Edge, Safari 14 for macOS/iOS/iPadOS, Opera