{"id":21065608,"url":"https://github.com/adaptlearning/adapt-contrib-hotgraphic","last_synced_at":"2025-05-16T02:33:25.349Z","repository":{"id":12341303,"uuid":"14983621","full_name":"adaptlearning/adapt-contrib-hotgraphic","owner":"adaptlearning","description":"A contributed hot graphic component that enables a user to click on hot spots over an image and display a detailed popup that includes an image with text.","archived":false,"fork":false,"pushed_at":"2025-03-28T13:31:40.000Z","size":531,"stargazers_count":3,"open_issues_count":9,"forks_count":45,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-03-28T14:30:32.056Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adaptlearning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-12-06T13:38:23.000Z","updated_at":"2025-03-03T09:52:37.000Z","dependencies_parsed_at":"2023-02-19T12:30:41.184Z","dependency_job_id":"f676c521-d723-4d76-b3a9-66eadd463c23","html_url":"https://github.com/adaptlearning/adapt-contrib-hotgraphic","commit_stats":null,"previous_names":[],"tags_count":103,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-hotgraphic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-hotgraphic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-hotgraphic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-hotgraphic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adaptlearning","download_url":"https://codeload.github.com/adaptlearning/adapt-contrib-hotgraphic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254456356,"owners_count":22074155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T17:55:46.121Z","updated_at":"2025-05-16T02:33:25.046Z","avatar_url":"https://github.com/adaptlearning.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adapt-contrib-hotgraphic\n\n**Hot Graphic** is a *presentation component* bundled with the [Adapt framework](https://github.com/adaptlearning/adapt_framework).\n\u003cimg src=\"https://github.com/adaptlearning/documentation/blob/master/04_wiki_assets/plug-ins/images/hotgraphic01.gif\" alt=\"Hot Graphic in action\"\u003e\n\nWhen 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](https://github.com/adaptlearning/adapt-contrib-hotgraphic/wiki) for more information about its functionality and for explanations of key properties.\n\nIn 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](#_pin-object) setting for more information) or, using the [_useGraphicsAsPins](#_usegraphicsaspins-boolean) setting, create a 'tiled layout' of images where each 'tile' acts as a hot spot.\n\nBy default, when the viewport size changes to the smallest range, this component will behave like a [**Narrative** component](https://github.com/adaptlearning/adapt-contrib-narrative). 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](#_isnarrativeonmobile-boolean) setting to `false`.\n\n## Installation\n\nAs one of Adapt's *[core components](https://github.com/adaptlearning/adapt_framework/wiki/Core-Plug-ins-in-the-Adapt-Learning-Framework#components),* **Hot Graphic** is included with the [installation of the Adapt framework](https://github.com/adaptlearning/adapt_framework/wiki/Manual-installation-of-the-Adapt-framework#installation) and the [installation of the Adapt authoring tool](https://github.com/adaptlearning/adapt_authoring/wiki/Installing-Adapt-Origin).\n\n* If **Hot Graphic** has been uninstalled from the Adapt framework, it may be reinstalled.\nWith the [Adapt CLI](https://github.com/adaptlearning/adapt-cli) installed, run the following from the command line:\n    ```console\n    adapt install adapt-contrib-hotgraphic\n    ```\n\n    Alternatively, this component can also be installed by adding the following line of code to the *adapt.json* file:\n    ```json\n    \"adapt-contrib-hotgraphic\": \"*\"\n    ```\n    Then running the command:\n    ```console\n    adapt install\n    ```\n    (This second method will reinstall all plug-ins listed in *adapt.json*.)\n\n* If **Hot Graphic** has been uninstalled from the Adapt authoring tool, it may be reinstalled using the [Plug-in Manager](https://github.com/adaptlearning/adapt_authoring/wiki/Plugin-Manager).\n\u003cdiv float align=right\u003e\u003ca href=\"#top\"\u003eBack to Top\u003c/a\u003e\u003c/div\u003e\n\n## Settings Overview\n\nThe attributes listed below are used in *components.json* to configure **Hot Graphic**, and are properly formatted as JSON in [*example.json*](https://github.com/adaptlearning/adapt-contrib-hotgraphic/blob/master/example.json). Visit the [**Hot Graphic** wiki](https://github.com/adaptlearning/adapt-contrib-hotgraphic/wiki) for more information about how they appear in the [authoring tool](https://github.com/adaptlearning/adapt_authoring/wiki).\n\n## Attributes\n\n[**core model attributes**](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes): These are inherited by every Adapt component. [Read more](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes).\n\n### \\_component (string):\nThis must be set to: `\"hotgraphic\"`.\n\n### \\_classes (string):\nCSS 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.\n\n### \\_layout (string):\nThis defines the horizontal position of the component in the block. Acceptable values are `full`, `left` or `right`.\n\n### instruction (string):\nThis optional text appears above the component. It is frequently used to\nguide the learner’s interaction with the component.\n\n### mobileBody (string):\nThis 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](#_isnarrativeonmobile-boolean) setting is set to `false`).\n\n### mobileInstruction (string):\nThis 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](#_isnarrativeonmobile-boolean) setting is set to `false`).\n\n### \\_isMobileTextBelowImage (boolean):\nLike `mobileBody` and `mobileInstruction`, `_isMobileTextBelowImage` is only applicable when `device.screenSize` is `small` (i.e. when viewed on mobile devices, except when the [_isNarrativeOnMobile](#_isnarrativeonmobile-boolean) 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.\n\n### \\_setCompletionOn (string):\nDetermines 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.\n\n### \\_canCycleThroughPagination (boolean):\nEnables 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`.\n\n### \\_hidePagination (boolean):\nWhen 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`.\n\n### \\_isNarrativeOnMobile (boolean):\nWhen 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`.\n\n### \\_isMobileTextBelowImage (boolean):\nIf 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`\n\n### \\_isStackedOnMobile (boolean):\nIf 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`\n\n### \\_useNumberedPins (boolean):\nIf 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`.\n\n### \\_useGraphicsAsPins (boolean):\nIf 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](example.json) for a working example. The default is `false`.\n\n### \\_hasStaticTooltips (boolean):\nIf set to `true`, tooltips (if enabled) will always be shown rather than only on hover.\n\n### \\_isRound (boolean):\nIf 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`.\n\n### \\_pinOffsetOrigin (boolean):\nIf 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`.\n\n### \\_tooltip (object):\n\n#### \\_isEnabled (boolean):\nWhen 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`.\n\n#### text (string):\nThe tooltip text to display for the item.\n\n#### \\_position (string):\nThe 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`.\n\n#### \\_classes (string):\nCSS 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.\n\n### \\_graphic (object):\nThe graphic object that defines the image over which the hot spots are rendered (except when the [_useGraphicsAsPins](#_usegraphicsaspins-boolean) setting is enabled). It contains the following settings:\n\n#### src (string):\nFile name (including path) of the image. Path should be relative to the `src` folder (e.g. `\"course/en/images/origami-menu-two.jpg\"`).\n\n#### alt (string):\nThe alternative text for this image. Assign [alt text](https://github.com/adaptlearning/adapt_framework/wiki/Providing-good-alt-text) to images that convey course content only.\n\n#### attribution (string):\nOptional text to be displayed as an [attribution](https://wiki.creativecommons.org/Best_practices_for_attribution). By default it is displayed below the image. Adjust positioning by modifying CSS. Text can contain HTML tags, e.g., `Copyright © 2015 by \u003cb\u003eLukasz 'Severiaan' Grela\u003c/b\u003e`.\n\n### \\_items (array):\nMultiple items may be created. Each entry in the array should be an object, containing the following settings:\n\n#### \\_top (number):\nEach 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.\n\n#### \\_left (number):\nEnter a percentage value (0-100) that this item should be from the left border of the main graphic. Not required for tile/grid layout.\n\n#### title (string):\nThis is the title text for the hot spot's pop-up.\n\n#### body (string):\nThis is the main text for a hot spot pop-up.\n\n#### strapline (string):\nThis text is displayed when `device.screenSize` is `small` (i.e. when viewed on mobile devices, except when the [_isNarrativeOnMobile](#_isnarrativeonmobile-boolean) setting is set to `false`). It is presented in a title bar above the image.\n\n#### \\_imageAlignment (string):\nDefines the alignment of the item image in the pop up. The default alignment is `right`. Not required for tile/grid layout.\n\n* `\"left\"`: Image aligned to the left of the text area\n* `\"top\"`: Image aligned above the text area\n* `\"right\"`: Image aligned to the right of the text area\n* `\"bottom\"`: Image aligned below the text area\n\n#### \\_classes (string):\nCSS class name(s) to be applied to the popup item. Classes available by default are:\n\n* `\"hide-desktop-image\"`: Hides the pop up image in desktop view\n* `\"hide-popup-image\"`: Hides the pop up image for all screen sizes\n\nAny other classes need to be predefined in one of the Less files. Separate multiple classes with a space.\n\n#### \\_graphic (object):\nThe 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](#_usegraphicsaspins-boolean) setting allows for it to be used as a 'tile' in the main image instead). It contains the following settings:\n\n##### src (string):\nFile name (including path) of the image. Path should be relative to the `src` folder (e.g. `\"course/en/images/origami-menu-two.jpg\"`).\n\n##### alt (string):\nThe alternative text for this image. Assign [alt text](https://github.com/adaptlearning/adapt_framework/wiki/Providing-good-alt-text) to images that convey course content only.\n\n##### attribution (string):\nOptional text to be displayed as an [attribution](https://wiki.creativecommons.org/Best_practices_for_attribution). By default it is displayed below the image. Adjust positioning by modifying CSS. Text can contain HTML tags, e.g., `Copyright © 2015 by \u003cb\u003eLukasz 'Severiaan' Grela\u003c/b\u003e`.\n\n##### \\_classes (string):\nCSS class name(s) to be applied to hotgraphic pin or, alternatively, to the hotspot tile when [_useGraphicsAsPins](#_usegraphicsaspins-boolean) is set to `true`. The class must be predefined in one of the Less files. Separate multiple classes with a space.\n\n#### \\_pin (object):\nOptional image that can appear instead of the default pin icon. See [example.json](example.json#L117-L160) for a working example. It contains the following settings:\n\n##### src (string):\nFile name (including path) of the image. Path should be relative to the `src` folder (e.g. `\"course/en/images/origami-menu-two.jpg\"`).\n\n##### alt (string):\nThe alternative text for this image. Assign [alt text](https://github.com/adaptlearning/adapt_framework/wiki/Providing-good-alt-text) to images that convey course content only.\n\n## Accessibility\n**Hot Graphic** has been assigned a descriptive label using the [aria-label](https://github.com/adaptlearning/adapt_framework/wiki/Aria-Labels) attribute: **ariaRegion**.\n\nOther 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**.\n\nThese 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*](https://github.com/adaptlearning/adapt-contrib-hotgraphic/blob/master/properties.schema) (or Project settings \u003e Globals in the Adapt Authoring Tool).\n\u003cdiv float align=right\u003e\u003ca href=\"#top\"\u003eBack to Top\u003c/a\u003e\u003c/div\u003e\n\n----------------------------\n\u003ca href=\"https://community.adaptlearning.org/\" target=\"_blank\"\u003e\u003cimg src=\"https://github.com/adaptlearning/documentation/blob/master/04_wiki_assets/plug-ins/images/adapt-logo-mrgn-lft.jpg\" alt=\"adapt learning logo\" align=\"right\"\u003e\u003c/a\u003e\n**Author / maintainer:** Adapt Core Team with [contributors](https://github.com/adaptlearning/adapt-contrib-hotgraphic/graphs/contributors)\u003cbr\u003e\n**Accessibility support:** WAI AA\u003cbr\u003e\n**RTL support:** Yes\u003cbr\u003e\n**Cross-platform coverage:** Chrome, Chrome for Android, Firefox (ESR + latest version), Edge, Safari 14 for macOS/iOS/iPadOS, Opera\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-hotgraphic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadaptlearning%2Fadapt-contrib-hotgraphic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-hotgraphic/lists"}