{"id":21065615,"url":"https://github.com/adaptlearning/adapt-contrib-gmcq","last_synced_at":"2025-05-16T02:33:28.606Z","repository":{"id":12905934,"uuid":"15583171","full_name":"adaptlearning/adapt-contrib-gmcq","owner":"adaptlearning","description":"A graphical multiple choice question","archived":false,"fork":false,"pushed_at":"2024-11-08T12:52:49.000Z","size":460,"stargazers_count":4,"open_issues_count":3,"forks_count":32,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-11-08T13:41:47.025Z","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":"2014-01-02T12:32:24.000Z","updated_at":"2024-11-08T12:44:50.000Z","dependencies_parsed_at":"2023-02-18T17:10:17.304Z","dependency_job_id":"b1ecc1f3-88d1-4bed-81d8-bf2ae3be57d0","html_url":"https://github.com/adaptlearning/adapt-contrib-gmcq","commit_stats":null,"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-gmcq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-gmcq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-gmcq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptlearning%2Fadapt-contrib-gmcq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adaptlearning","download_url":"https://codeload.github.com/adaptlearning/adapt-contrib-gmcq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225402090,"owners_count":17468828,"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:48.965Z","updated_at":"2024-11-19T17:55:49.783Z","avatar_url":"https://github.com/adaptlearning.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adapt-contrib-gmcq\n\n**Graphical Multiple Choice Question (GMCQ)** is a *question component* bundled with the [Adapt framework](https://github.com/adaptlearning/adapt_framework).\n\n\u003cimg src=\"https://github.com/adaptlearning/documentation/blob/master/04_wiki_assets/plug-ins/images/gmcq01.gif\" alt=\"graphical multiple choice question in action\" \u003e\n\nIt presents possible answers in the form of graphics or images. **GMCQ** is a variation on [**MCQ**](https://github.com/adaptlearning/mcq/wiki). It can be configured with a single correct answer or multiple correct answers. Upon submission, feedback is provided via the [**Tutor** extension](https://github.com/adaptlearning/adapt-contrib-tutor), if installed. Feedback can be provided for correct, incorrect and partially correct answers. The number of attempts allowed may be configured.\n\n[Visit the **GMCQ** wiki](https://github.com/adaptlearning/adapt-contrib-gmcq/wiki) for more information about its functionality and for explanations of key properties.\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),* **GMCQ** 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 **GMCQ** 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`adapt install adapt-contrib-gmcq`\n\n    Alternatively, this component can also be installed by adding the following line of code to the *adapt.json* file:\n    `\"adapt-contrib-gmcq\": \"*\"`\n    Then running the command:\n    `adapt install`\n    (This second method will reinstall all plug-ins listed in *adapt.json*.)\n\n* If **GMCQ** 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\n## Settings Overview\n\nThe attributes listed below are used in *components.json* to configure **GMCQ**, and are properly formatted as JSON in [*example.json*](https://github.com/adaptlearning/adapt-contrib-gmcq/blob/master/example.json). Visit the [**GMCQ** wiki](gmcq/wiki) for more information about how they appear in the [authoring tool](https://github.com/adaptlearning/adapt_authoring/wiki).\n\n\u003cdiv float align=right\u003e\u003ca href=\"#top\"\u003eBack to Top\u003c/a\u003e\u003c/div\u003e\n\n### Attributes\n\nIn addition to the attributes specifically listed below, [*question components*](https://github.com/adaptlearning/adapt_framework/wiki/Core-Plug-ins-in-the-Adapt-Learning-Framework#question-components) can implement the following sets of attributes:\n+ [**core model attributes**](https://github.com/adaptlearning/adapt_framework/wiki/Core-model-attributes): These are inherited by every Adapt component. They have no default values. Like the attributes below, their values are assigned in *components.json*.\n+ [**core buttons**](https://github.com/adaptlearning/adapt_framework/wiki/Core-Buttons): Default values are found in *course.json*, but may be overridden by **GMCQ's** model in *components.json*.\n\n**\\_component** (string): This value must be: `gmcq`.\n\n**\\_classes** (string): CSS class name to be applied to **GMCQ**’s containing `div`. The class must be predefined in one of the Less files. Separate multiple classes with a space.\n\n**\\_layout** (string): This defines the horizontal position of the component in the block. Acceptable values are `full`, `left` or `right`.\n\n**instruction** (string): This optional text appears above the component. It is frequently used to\nguide the learner’s interaction with the component.\n\n**ariaQuestion** (string): This will be read out by screen readers instead of reading the title, body \u0026 instruction fields when focusing on the group or radiogroup.\n\n**\\_attempts** (integer): This specifies the number of times a learner is allowed to submit an answer. The default is `1`.\n\n**\\_shouldDisplayAttempts** (boolean): Determines whether or not the text set in **remainingAttemptText** and **remainingAttemptsText** will be displayed. These two attributes are part of the [core buttons](https://github.com/adaptlearning/adapt_framework/wiki/Core-Buttons) attribute group. The default is `false`.\n\n**\\_hasItemScoring** (boolean): When `false`, this question scores 0 for incorrect and `_questionWeight` for correct. When `true`, this question scores by summing the `_score` of the selected items.\n\n**\\_questionWeight** (number): When `_hasItemScoring` is `false`, this is the question score for a correct response. This number is used in calculations of the final score reported to the LMS.\n\n**\\_isRandom** (boolean): Setting this value to `true` will cause the **\\_items** to appear in a random order each time the component is loaded. The default is `false`.\n\n**\\_selectable** (number): Defines the number of **\\_items**, or answers, that can be selected. If the value of **\\_selectable** is `1`, **\\_items** will be presented with HTML radio buttons. If the value is greater than `1`, they will be presented with HTML checkboxes. This number can be smaller, match or exceed the number of **\\_items** whose **_shouldBeSelected** is set to `true`. The default is `1`.\n\n**\\_canShowModelAnswer** (boolean): Setting this to `false` prevents the [**\\_showCorrectAnswer** button](https://github.com/adaptlearning/adapt_framework/wiki/Core-Buttons) from being displayed. The default is `true`.\n\n**\\_canShowCorrectness** (boolean): Setting this to `true` replaces the associated `_canShowModelAnswer` toggle button and displays correctness directly on the component items. The default is `false`.\n\n**\\_canShowFeedback** (boolean): Setting this to `false` disables feedback, so it is not shown to the user. The default is `true`.\n\n**\\_canShowMarking** (boolean): Setting this to `false` prevents ticks and crosses being displayed on question completion. The default is `true`.\n\n**\\_recordInteraction** (boolean) Determines whether or not the learner's answers will be recorded to the LMS via cmi.interactions. Default is `true`. For further information, see the entry for `_shouldRecordInteractions` in the README for [adapt-contrib-spoor](https://github.com/adaptlearning/adapt-contrib-spoor).\n\n**\\_columns** (number): Defines the number of columns wide the **\\_items** are displayed in. If the value of **\\_columns** is `2`, each **\\_items** will be 50% wide. Similarly, if the value of **\\_columns** is `3`, each **\\_items** will be 33.3% wide. In mobile view, the width of each **\\_items** is 50%.\n\n**\\_isRound** (boolean): If set to `true`, the item 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**\\_items** (array): Each *item* represents one choice for the multiple choice question and contains values for **text**, **\\_shouldBeSelected**, **feedback**, and **\\_graphic**.\n\n\u003e**text** (string): Optional text that is displayed as part of the multiple choice option.\n\n\u003e**altText** (string): This will be read out by screen readers instead of reading `text`.\nOptional for providing alternative text, for example, to specify how a word should be pronounced.\n\n\u003e**\\_shouldBeSelected** (boolean): Value can be `true` or `false`. Use `true` for items that must be selected for a correct answer. The value of **\\_selectable** can be smaller, match or exceed the number of **\\_items** where **\\_shouldBeSelected** is set to `true`.\n\n\u003e**\\_isPartlyCorrect** (boolean): Determines whether the *item* when selected marks the question as partly correct. Value can be `true` or `false`. Default is `false`.\n\n\u003e**feedback** (string): This attribute is used only when the value for **\\_selectable** is set to `1` (i.e., radio button style questions). This text will be shown if the learner selects this item, and it is an incorrect answer.\n\n\u003e**\\_graphic** (object): The image that appears as a possible answer. It contains values for **large**, **small**, **alt**, and **title**.\n\n\u003e\u003e**large** (string): File name (including path) of the image used with large device width. Path should be relative to the *src* folder (e.g., *course/en/images/origami-menu-two.jpg*).\n\n\u003e\u003e**small** (string): File name (including path) of the image used with small device width. Path should be relative to the *src* folder (e.g., *course/en/images/origami-menu-two.jpg*).\n\n\u003e\u003e**alt** (string): The 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. Avoid duplication if the item **text** already provides context and leave blank.\n\n\u003e\u003e**attribution** (string): Optional 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\u003e**\\_score** (number): If `_hasItemScoring` is `true`, when selected, item scores are summed to give the question score.\n\n**\\_feedback** (object): If the [**Tutor** extension](https://github.com/adaptlearning/adapt-contrib-tutor) is enabled, these various texts will be displayed depending on the submitted answer. **\\_feedback**\ncontains values for three types of answers: **correct**, **\\_incorrect**, and **\\_partlyCorrect**. Some attributes are optional. If they are not supplied, the default that is noted below will be used.\n\n\u003e**title** (string): Title text for the feedback that will be displayed when the question is submitted.\n\n\u003e**altTitle** (string): This will be read out by screen readers as an alternative heading if no visual heading is included.\n\n\u003e**correct** (string): Text that will be displayed when the submitted answer is correct.\n\n\u003e**\\_incorrect** (object): Texts that will be displayed when the submitted answer is incorrect. It contains values that are displayed under differing conditions: **final** and **notFinal**.\n\n\u003e\u003e**final** (string): Text that will be displayed when the submitted answer is incorrect and no more attempts are permitted.\n\n\u003e\u003e**notFinal** (string): Text that will be displayed when the submitted answer is incorrect while more attempts are permitted. This is optional\u0026mdash;if you do not supply it, the **\\_incorrect.final** feedback will be shown instead.\n\n\u003e**\\_partlyCorrect** (object): Texts that will be displayed when the submitted answer is partially correct. It contains values that are displayed under differing conditions: **final** and **notFinal**.\n\n\u003e\u003e**final** (string): Text that will be displayed when the submitted answer is partly correct and no more attempts are permitted. This is optional\u0026mdash;if you do not supply it, the **\\_incorrect.final** feedback will be shown instead.\n\n\u003e\u003e**notFinal** (string): Text that will be displayed when the submitted answer is partly correct while more attempts are permitted. This is optional\u0026mdash;if you do not supply it, the **\\_incorrect.notFinal** feedback will be shown instead.\n\n### Notes\nIf you don't need this component to display a different image for large/small screen sizes, you can use **src** (instead of **large** and **small**) to specify an image that will be displayed for all screen sizes.\n\n## Accessibility\n**Graphical Multiple Choice Question** has been assigned a descriptive label using the [aria-label](https://github.com/adaptlearning/adapt_framework/wiki/Aria-Labels) attribute: **ariaRegion**.\n\nWhen **Graphical Multiple Choice Question** is used with Adapt Framework v5.12.0 (or better), it supports announcing the correct/learner answer to screen readers (via an an [ARIA Live Region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)) when the Correct Answer button is toggled by the learner. The following attributes are used to provide this functionality: **ariaCorrectAnswer**, **ariaCorrectAnswers**, **ariaUserAnswer**, **ariaUserAnswers**.\n\nThese ARIA labels are not visible elements; they are used 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._components._gmcq` object in **course.json** (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## Limitations\n\nNo known limitations.\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-gmcq/graphs/contributors)\n**Accessibility support:** WAI AA\n**RTL support:** Yes\n**Cross-platform coverage:** Chrome, Chrome for Android, Firefox (ESR + latest version), Edge, IE11, Safari 14 for macOS/iOS/iPadOS, Opera\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-gmcq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadaptlearning%2Fadapt-contrib-gmcq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptlearning%2Fadapt-contrib-gmcq/lists"}