phet-io-test-sim PhET-iO Guide for Instructional Designers

This is just for testing, and was originally copied directly from ph-scale

Simulation Links

Customization using Query Parameters

Query parameters can be used to customize the simulation. Query parameters are added by appending a ? to the sim URL, and separating each query parameter with a &.

Example: set sim language to Spanish (locale=es) and only include the first screen (screens=1)

Standalone sim: ../../phet-io-test-sim_all_phet-io.html?postMessageOnError&phetioStandalone&locale=es&screens=1
Studio: ../../wrappers/studio/?locale=es&screens=1

Query parameters used within PhET-iO Studio will be maintained when the HTML code for the simulation and its customization wrapper is launched or downloaded.

Simulation-specific Query Parameters

Query Parameter	Values	Description	Examples
`autofill`	`true` `false`	If true, the dropper will autofill the beaker to 0.50 L when switching solutes. Default is true.	`autofill=false` Standalone sim Studio

General Query Parameters

Query Parameter	Values	Description	Examples
`locale`	`en` `es` `fr` `zh_CN` etc.	The value is the locale code. See the sim page for available locales. Default is English.	`locale=es` Standalone sim Studio
`screens`	`1` `2` `3`	Specifies which screens are included in the sim and their order. Note: It is also possible to customize the screens within PhET-iO studio, but we do not recommend it. Please use the query parameter. Default is all screens.	`screens=1` Standalone sim Studio `screens=2,1` Standalone sim Studio
`initialScreen`	`1` `2` `3`	Used to specify the screen open on startup. Default is home screen.	`initialScreen=2` Standalone sim Studio
`homeScreen`	`true` `false`	If false, hides the home screen. Default is true.	`homeScreen=false` Standalone sim Studio
`allowLinks`	`true` `false`	If false, disables external links. Default is true.	`allowLinks=false` Standalone sim Studio

Best Practices for Customizing with PhET-iO Studio

The simulation can be customized via direct simulation interaction or the PhET-iO element tree.
- For example, the Molecule Count can be turned on using the checkbox in the simulation, or by navigating to the corresponding element in the tree (phScale.microScreen.view.viewProperties.moleculeCountVisibleProperty) and setting the current value to true.
When customizing the simulation through the element tree, begin with the "Featured" PhET-iO elements. If you have trouble locating the customization feature you are seeking, try looking at "All" PhET-iO elements.
Each screen is separated into a "model" and a "view". Generally, elements related to the underlying model values can be found in the "model" while elements related to the appearance within the simulation are controlled in the "view". Elements in the "view" may occasionally be linked to elements in the "model", which will be indicated by the appearance of *property in the studio tree.
Many user interface components have common properties including:
- visibleProperty: used to show/hide elements
- enabledProperty: used to enable/disable elements
- pickableProperty: used to make elements unclickable/unmovable
If you want to hide a group of elements, you can do so by setting the visibleProperty of the top-level element to false.
- For example, if you would like to hide both checkboxes on the Micro screen, you can hide the entire panel containing them (set phScale.microScreen.view.beakerControlPanel.visibleProperty to false). You do not need to hide each individual checkbox.
To test customizations, the HTML code for the simulation and its customization wrapper can be launched or downloaded using the buttons in Studio.
The HTML output can be "Production" or "Development". Production is used when you are ready for student-facing content, or when there are no additional changes that a developer will make to the Customization Wrapper. Development is used when a software developer will add additional API functionality, such as logging one of the backend data streams from the sim, hooking the sim up to an external table, or such. The only line change in the wrapper code is debug: true. This should be changed to debug: false when development is done, and you finalize the wrapper for student-facing production use.

Understanding the Customization Wrapper generated by PhET-iO Studio

Conceptually, the HTML code generated by PhET-iO Studio acts upon a base version of the PhET-iO simulation to create a particular customization. The PhET-iO simulation is the same in all cases, and is running in an iFrame that is launched by the Customization Wrapper code.

Basic webpage structure of an embedded, customized PhET-iO simulation alt text "PhET-iO sim webpage structure"

The HTML code in the Customization Wrapper includes a basic template for adding additional capabilities. For instance, this section of code from the Customization Wrapper is used to control whether a backend data stream logging the state of the simulation is enabled (true) or not (false):
```
 /**
  * Option to add sim state information
  * {boolean}
  */
 emitStates: false,
```