WebsiteComponent

Defined in: parser/types.ts:1614

The WebsiteComponent interface is used to define the properties of a website component. A WebsiteComponent is used to render an iframe with a website inside of it. This can be used to display an external website or an html file that is located in the public folder.

{
  "type": "website",
  "path": "<study-name>/assets/website.html"
}

To pass a data from the config to the website, you can use the parameters field as below:

{
  "type": "website",
  "path": "<study-name>/website.html",
  "parameters": {
    "barData": [0.32, 0.01, 1.2, 1.3, 0.82, 0.4, 0.3]
  },
  "response": [
    {
      "id": "barChart",
      "prompt": "Your selected answer:",
      "location": "belowStimulus",
      "type": "reactive"
    }
  ]
}

In the website.html file, by including revisit-communicate.js, you can use the Revisit.onDataReceive method to retrieve the data, and Revisit.postAnswers to send the user's responses back to the reVISit as shown in the example below:

<script src="../../revisitUtilities/revisit-communicate.js"></script>
<script>
Revisit.onDataReceive((data) => {
    const barData = data['barData'];
    ...
  });

  // Call out that 'barChart' needs to match ID in 'response' object
  Revisit.postAnswers({ barChart: userAnswer });
  </script>

If the html website implements Trrack provenance tracking, create the instance through Revisit.createTrrack. reVISit subscribes before returning the instance and automatically reports apply, undo, redo, and other traversals.

const trrack = Revisit.createTrrack({
    initializeTrrack,
    initialState,
    registry
  });

As an alternative to passing data over Revisit.onDataReceive, you can set templated to true. The HTML file is then fetched and compiled as a Handlebars template before it is rendered, exactly like a markdown component's file, so parameters (and the {{REVISIT.*}} data frame and the lookupAnswers, lookupParameters, and lookupCorrectAnswer helpers and their Rel forms) can be substituted directly into the markup:

{
  "type": "website",
  "path": "<study-name>/assets/chart.html",
  "templated": true,
  "parameters": {
    "country": "France",
    "barData": "[0.32,0.01,1.2]"
  }
}

<h1>Capital of {{country}}</h1>
<script>
  // barData is a pre-serialized JSON string. Triple braces preserve it without HTML escaping.
  // Only insert trusted parameters this way, never participant answers.
  const barData = {{{barData}}};
</script>

A few things to know about templated websites:

• The file is rendered from its compiled contents rather than from its URL, so it is compiled once when the trial loads and is not re-compiled as answers change.
• Relative paths inside the file (scripts, stylesheets, images) keep working; reVISit injects a <base> tag pointing at the file's folder.
• revisit-communicate.js keeps working, but the file must reference the shared revisitUtilities/revisit-communicate.js rather than an old vendored copy of it.
• templated is ignored when path points at an external website.

Extends

• BaseIndividualComponent

Properties

Property	Type	Description	Inherited from	Defined in
allowFailedTraining?	boolean	Allow continuing with incorrect answers after attempts are exhausted. Overrides uiConfig.allowFailedTraining. Defaults to true.	BaseIndividualComponent.allowFailedTraining	parser/types.ts:1419
captureGamepad?	boolean	Whether or not to capture game controller input into windowEvents. If present, will override the capture gamepad setting in the uiConfig.	BaseIndividualComponent.captureGamepad	parser/types.ts:1429
clickToRecord?	boolean	Enables a click-and-hold microphone button instead of continuous recording. When true, audio is muted by default and is recorded only while the button is held. When false, recording starts immediately and can be paused/resumed via the microphone button. Defaults to false.	BaseIndividualComponent.clickToRecord	parser/types.ts:1423
colorMode?	"light" | "dark"	The iframe's color scheme. Defaults to the study's color mode. The embedded page must support color schemes.	-	parser/types.ts:1619
correctAnswer?	Answer[]	The correct answer to the component. This is used for training trials where the user is shown the correct answer after a guess.	BaseIndividualComponent.correctAnswer	parser/types.ts:1367
description?	string	The description of the component. This is used to identify and provide additional information for the component in the admin panel.	BaseIndividualComponent.description	parser/types.ts:1371
enumerateQuestions?	boolean	Whether to prepend questions with their index (+ 1). This should only be used when all questions are in the same location, e.g. all are in the side bar. If present, will override the enumeration of questions setting in the uiConfig.	BaseIndividualComponent.enumerateQuestions	parser/types.ts:1431
helpTextPath?	string	The path to the help text file. This is displayed when a participant clicks help. Markdown is supported. If present, will override the help text path set in the uiConfig.	BaseIndividualComponent.helpTextPath	parser/types.ts:1389
hideCheckAnswerButton?	boolean	Hide the Check Answer button and grade answers on Next instead. Defaults to false. Feedback must be enabled by provideFeedback or answer-level feedback.	BaseIndividualComponent.hideCheckAnswerButton	parser/types.ts:1415
instruction?	string	The instruction of the component. This is used to identify and provide additional information for the component in the admin panel.	BaseIndividualComponent.instruction	parser/types.ts:1383
instructionLocation?	ConfigResponseBlockLocation	The location of the instructions. If present, will override the instruction location setting in the uiConfig.	BaseIndividualComponent.instructionLocation	parser/types.ts:1385
meta?	Record<string, unknown>	The meta data for the component. This is used to identify and provide additional information for the component in the admin panel.	BaseIndividualComponent.meta	parser/types.ts:1369
nextButtonAlignment?	NextButtonAlignment	The horizontal alignment of the navigation action group. If present, will override the alignment setting in the uiConfig.	BaseIndividualComponent.nextButtonAlignment	parser/types.ts:1397
nextButtonAutoAdvanceTime?	number	The time in milliseconds after which the participant is automatically advanced to the next component without saving answers from the current component.	BaseIndividualComponent.nextButtonAutoAdvanceTime	parser/types.ts:1403
nextButtonAutoAdvanceWarningMessage?	string	The warning message shown before auto-advance. Include {seconds} to interpolate the remaining number and {unit} to interpolate second/seconds.	BaseIndividualComponent.nextButtonAutoAdvanceWarningMessage	parser/types.ts:1407
nextButtonAutoAdvanceWarningTime?	number	The time in milliseconds before auto-advance when the warning message is shown. Defaults to 30000.	BaseIndividualComponent.nextButtonAutoAdvanceWarningTime	parser/types.ts:1405
nextButtonDisableTime?	number	The time in milliseconds to wait before the next button is disabled. If present, will override the next button disable time setting in the uiConfig.	BaseIndividualComponent.nextButtonDisableTime	parser/types.ts:1401
nextButtonEnableTime?	number	The time in milliseconds to wait before the next button is enabled. If present, will override the next button enable time setting in the uiConfig.	BaseIndividualComponent.nextButtonEnableTime	parser/types.ts:1399
nextButtonLocation?	ConfigResponseBlockLocation	The location of the next button. If present, will override the next button location setting in the uiConfig.	BaseIndividualComponent.nextButtonLocation	parser/types.ts:1395
nextButtonText?	string	The text to display on the next button. If present, will override the next button text setting in the uiConfig.	BaseIndividualComponent.nextButtonText	parser/types.ts:1393
nextOnEnter?	boolean	Whether enter key should move to the next question. If present, will override the enter key setting in the uiConfig.	BaseIndividualComponent.nextOnEnter	parser/types.ts:1391
parameters?	Record<string, unknown>	The parameters passed to the component. These can be used for variable substitution: in a react-component, they're available as the parameters prop; in this component's instruction field and its responses' prompt, secondaryText, and infoText fields, they're substituted as Handlebars variables ({{variable}}). The same substitution also applies inside markdown files, and inside a website component's HTML file when its templated field is true.	BaseIndividualComponent.parameters	parser/types.ts:1387
path	string	The path to the website. This should be a relative path from the public folder or could be an external website.	-	parser/types.ts:1617
previousButton?	boolean	Whether to show the previous button. If present, will override the previous button setting in the uiConfig.	BaseIndividualComponent.previousButton	parser/types.ts:1409
previousButtonText?	string	The text that is displayed on the previous button. If present, will override the previous button text setting in the uiConfig.	BaseIndividualComponent.previousButtonText	parser/types.ts:1411
provideFeedback?	boolean	Enable answer checking and feedback. Explicit false disables it even with answer-level feedback. When omitted, answer-level feedback enables it before falling back to uiConfig.provideFeedback.	BaseIndividualComponent.provideFeedback	parser/types.ts:1413
recordAudio?	boolean	Whether or not we want to utilize think-aloud features. If present, will override the record audio setting in the uiConfig.	BaseIndividualComponent.recordAudio	parser/types.ts:1421
recordScreen?	boolean	Whether or not we want to utilize screen recording feature. If present, will override the record screen setting in the uiConfig. If true, the uiConfig must have recordScreen set to true or the screen will not be captured. It's also required that the library component, $screen-recording.components.screenRecordingPermission, be included in the study at some point before this component to ensure permissions are granted and screen capture has started.	BaseIndividualComponent.recordScreen	parser/types.ts:1425
recordWebcam?	boolean	Whether or not we want to utilize webcam recording. If present, will override the record webcam setting in the uiConfig. Studies using webcam without screen capture should include the webcam permission component before this component. Studies combining webcam with screen capture should use the screen recording permission component.	BaseIndividualComponent.recordWebcam	parser/types.ts:1427
response	Response[]	The responses to the component	BaseIndividualComponent.response	parser/types.ts:1363
responseDividers?	boolean	Whether to show the response dividers. If present, will override the response dividers setting in the uiConfig.	BaseIndividualComponent.responseDividers	parser/types.ts:1433
responseOrder?	"fixed" | "random"	The order of the responses. Defaults to 'fixed'.	BaseIndividualComponent.responseOrder	parser/types.ts:1437
showTitle?	boolean	Controls whether the title should be hidden in the study. If present, will override the title setting in the uiConfig.	BaseIndividualComponent.showTitle	parser/types.ts:1379
showTitleBar?	boolean	Controls whether the title bar should be hidden in the study. If present, will override the title bar setting in the uiConfig.	BaseIndividualComponent.showTitleBar	parser/types.ts:1381
sidebarWidth?	number	The width of the left sidebar. If present, will override the sidebar width setting in the uiConfig.	BaseIndividualComponent.sidebarWidth	parser/types.ts:1377
style?	Styles	You can set styles here, using React CSSProperties, for example: {"width": 100} or {"width": "50%"}	BaseIndividualComponent.style	parser/types.ts:1441
stylesheetPath?	string	The path to the external stylesheet file.	BaseIndividualComponent.stylesheetPath	parser/types.ts:1439
templated?	boolean	Whether the HTML file should be compiled as a Handlebars template before it is rendered, so that {{parameter}} placeholders in the file are substituted. Defaults to false. Only applies to HTML files served from the study's public folder; it is ignored for external websites, which cannot be fetched and rewritten.	-	parser/types.ts:1621
trainingAttempts?	number	The number of training attempts allowed for the component. If present, will override the training attempts setting in the uiConfig.	BaseIndividualComponent.trainingAttempts	parser/types.ts:1417
type	"website"	-	-	parser/types.ts:1615
windowEventDebounceTime?	number	Debounce time in milliseconds for automatically tracked window events. If present, will override the window event debounce time setting in the uiConfig.	BaseIndividualComponent.windowEventDebounceTime	parser/types.ts:1435
withProgressBar?	boolean	Controls whether the progress bar is rendered. If present, will override the progress bar setting in the uiConfig.	BaseIndividualComponent.withProgressBar	parser/types.ts:1373
withSidebar?	boolean	Controls whether the left sidebar is rendered at all. Required to be true if your response's location is set to sidebar for any question. If present, will override the sidebar setting in the uiConfig.	BaseIndividualComponent.withSidebar	parser/types.ts:1375