Widget:ModelViewer: Difference between revisions

Latest revision as of 21:14, 31 July 2025

Embeds a 3D model using the <model-viewer> web component. Supports many configuration parameters like camera controls, AR, environment, and animations.

Template parameters[Edit template data]
Parameter		Description	Type	Status
Source	`src`	URL to the 3D model file (e.g., .glb or .gltf).	String	required
Alt text	`alt`	Alternative text describing the model. Default 3D Model	String	optional
Width	`width`	Width of the viewer (e.g., '100%' or '200px'). Default 240px	String	optional
Height	`height`	Height of the viewer (e.g., '100%' or '200px'). Default 165px	String	optional
Poster image	`poster`	URL to an image displayed before the model loads.	String	optional
Loading	`loading`	Loading behavior ('eager' or 'lazy').	String	optional
Reveal	`reveal`	When to reveal the model ('auto', 'interaction').	String	optional
With credentials	`withCredentials`	Use cross-origin credentials when fetching resources.	Boolean	optional
Auto-rotate	`autoRotate`	Automatically rotate the model.	Boolean	optional
Auto-rotate delay	`autoRotateDelay`	Delay before auto-rotation starts, in milliseconds.	String	optional
Camera controls	`cameraControls`	Allow user to control camera.	Boolean	optional
Background color	`backgroundColor`	CSS color value for the viewer background.	String	optional
AR mode	`ar`	Enable AR features.	Boolean	optional
iOS source	`iosSrc`	URL to the USDZ model for AR on iOS.	String	optional
AR button text	`arButtonText`	Custom text for the AR button.	String	optional
Loading text	`loadingText`	Custom text to display while loading.	String	optional
Error text	`errorText`	Custom text to display if loading fails.	String	optional

@@ Line 1: / Line 1: @@
-<widget xmlns="http://www.mediawiki.org/xmlns/widget/1.0">
+<span>
-  <param name="src" />
+<includeonly>
-  <param name="alt" default="3D model" />
+<model-viewer
-  <content>
+    src="<!--{$src|escape}-->"
-     <![CDATA[
+    alt="<!--{$alt|escape|default:'3D Model'}-->"
-      <model-viewer
+    style="width: <!--{$width|escape|default:'240px'}-->; height: <!--{$height|escape|default:'165px'}-->;"
-        src="$src"
-        alt="$alt"
+    <!--{if $poster}-->poster="<!--{$poster|escape}-->"<!--{/if}-->
-        camera-controls
+    <!--{if $loading}-->loading="<!--{$loading|escape}-->"<!--{/if}-->
-        auto-rotate
+    <!--{if $reveal}-->reveal="<!--{$reveal|escape}-->"<!--{/if}-->
-        style="width:100%; height:500px;">
+    <!--{if $withCredentials}-->with-credentials<!--{/if}-->
-      </model-viewer>
+    <!--{if $autoRotate}-->auto-rotate<!--{/if}-->
-    ]]>
+    <!--{if $autoRotateDelay}-->auto-rotate-delay="<!--{$autoRotateDelay|escape}-->"<!--{/if}-->
-  </content>
+    <!--{if $rotationPerSecond}-->rotation-per-second="<!--{$rotationPerSecond|escape}-->"<!--{/if}-->
-</widget>
+    <!--{if $cameraControls}-->camera-controls<!--{/if}-->
+    <!--{if $cameraOrbit}-->camera-orbit="<!--{$cameraOrbit|escape}-->"<!--{/if}-->
+    <!--{if $cameraTarget}-->camera-target="<!--{$cameraTarget|escape}-->"<!--{/if}-->
+    <!--{if $fieldOfView}-->field-of-view="<!--{$fieldOfView|escape}-->"<!--{/if}-->
+    <!--{if $minCameraOrbit}-->min-camera-orbit="<!--{$minCameraOrbit|escape}-->"<!--{/if}-->
+    <!--{if $maxCameraOrbit}-->max-camera-orbit="<!--{$maxCameraOrbit|escape}-->"<!--{/if}-->
+    <!--{if $minFieldOfView}-->min-field-of-view="<!--{$minFieldOfView|escape}-->"<!--{/if}-->
+    <!--{if $maxFieldOfView}-->max-field-of-view="<!--{$maxFieldOfView|escape}-->"<!--{/if}-->
+    <!--{if $interactionPrompt}-->interaction-prompt="<!--{$interactionPrompt|escape}-->"<!--{/if}-->
+    <!--{if $interactionPromptStyle}-->interaction-prompt-style="<!--{$interactionPromptStyle|escape}-->"<!--{/if}-->
+    <!--{if $interactionPromptThreshold}-->interaction-prompt-threshold="<!--{$interactionPromptThreshold|escape}-->"<!--{/if}-->
+    <!--{if $touchAction}-->touch-action="<!--{$touchAction|escape}-->"<!--{/if}-->
+    <!--{if $disableZoom}-->disable-zoom<!--{/if}-->
+    <!--{if $disablePan}-->disable-pan<!--{/if}-->
+    <!--{if $disableTap}-->disable-tap<!--{/if}-->
+    <!--{if $bounds}-->bounds="<!--{$bounds|escape}-->"<!--{/if}-->
+    <!--{if $animationName}-->animation-name="<!--{$animationName|escape}-->"<!--{/if}-->
+    <!--{if $animationCrossfadeDuration}-->animation-crossfade-duration="<!--{$animationCrossfadeDuration|escape}-->"<!--{/if}-->
+    <!--{if $autoplay}-->autoplay<!--{/if}-->
+    <!--{if $variantName}-->variant-name="<!--{$variantName|escape}-->"<!--{/if}-->
+    <!--{if $orientation}-->orientation="<!--{$orientation|escape}-->"<!--{/if}-->
+    <!--{if $scale}-->scale="<!--{$scale|escape}-->"<!--{/if}-->
+    <!--{if $environmentImage}-->environment-image="<!--{$environmentImage|escape}-->"<!--{/if}-->
+    <!--{if $skyboxImage}-->skybox-image="<!--{$skyboxImage|escape}-->"<!--{/if}-->
+    <!--{if $shadowIntensity}-->shadow-intensity="<!--{$shadowIntensity|escape}-->"<!--{/if}-->
+    <!--{if $shadowSoftness}-->shadow-softness="<!--{$shadowSoftness|escape}-->"<!--{/if}-->
+    <!--{if $exposure}-->exposure="<!--{$exposure|escape}-->"<!--{/if}-->
+     <!--{if $toneMapping}-->tone-mapping="<!--{$toneMapping|escape}-->"<!--{/if}-->
+    <!--{if $ar}-->ar<!--{/if}-->
+    <!--{if $arModes}-->ar-modes="<!--{$arModes|escape}-->"<!--{/if}-->
+    <!--{if $arScale}-->ar-scale="<!--{$arScale|escape}-->"<!--{/if}-->
+    <!--{if $arPlacement}-->ar-placement="<!--{$arPlacement|escape}-->"<!--{/if}-->
+    <!--{if $iosSrc}-->ios-src="<!--{$iosSrc|escape}-->"<!--{/if}-->
+    <!--{if $xrEnvironment}-->xr-environment<!--{/if}-->
+    <!--{if $backgroundColor}-->style="background-color: <!--{$backgroundColor|escape}-->;"<!--{/if}-->
+    <!--{if $generateSchema}-->generate-schema<!--{/if}-->
+    <!--{if $loadingText}--><div slot="progress-bar"><!--{$loadingText|escape}--></div><!--{/if}-->
+    <!--{if $errorText}--><div slot="error"><!--{$errorText|escape}--></div><!--{/if}-->
+    <!--{if $arButtonText}--><button slot="ar-button"><!--{$arButtonText|escape}--></button><!--{/if}-->
+    >
+</model-viewer>
+</includeonly>
+</span>
+<noinclude>
+{{Documentation}}
+<templatedata>
+{
+	"description": "Embeds a 3D model using the <model-viewer> web component. Supports many configuration parameters like camera controls, AR, environment, and animations.",
+	"params": {
+		"src": {
+			"label": "Source",
+			"description": "URL to the 3D model file (e.g., .glb or .gltf).",
+			"type": "string",
+			"required": true
+		},
+		"alt": {
+			"label": "Alt text",
+			"description": "Alternative text describing the model.",
+			"type": "string",
+			"default": "3D Model"
+		},
+		"width": {
+			"label": "Width",
+			"description": "Width of the viewer (e.g., '100%' or '200px').",
+			"type": "string",
+			"default": "240px"
+		},
+		"height": {
+			"label": "Height",
+			"description": "Height of the viewer (e.g., '100%' or '200px').",
+			"type": "string",
+			"default": "165px"
+		},
+		"poster": {
+			"label": "Poster image",
+			"description": "URL to an image displayed before the model loads.",
+			"type": "string"
+		},
+		"loading": {
+			"label": "Loading",
+			"description": "Loading behavior ('eager' or 'lazy').",
+			"type": "string"
+		},
+		"reveal": {
+			"label": "Reveal",
+			"description": "When to reveal the model ('auto', 'interaction').",
+			"type": "string"
+		},
+		"withCredentials": {
+			"label": "With credentials",
+			"description": "Use cross-origin credentials when fetching resources.",
+			"type": "boolean"
+		},
+		"autoRotate": {
+			"label": "Auto-rotate",
+			"description": "Automatically rotate the model.",
+			"type": "boolean"
+		},
+		"autoRotateDelay": {
+			"label": "Auto-rotate delay",
+			"description": "Delay before auto-rotation starts, in milliseconds.",
+			"type": "string"
+		},
+		"cameraControls": {
+			"label": "Camera controls",
+			"description": "Allow user to control camera.",
+			"type": "boolean"
+		},
+		"backgroundColor": {
+			"label": "Background color",
+			"description": "CSS color value for the viewer background.",
+			"type": "string"
+		},
+		"ar": {
+			"label": "AR mode",
+			"description": "Enable AR features.",
+			"type": "boolean"
+		},
+		"iosSrc": {
+			"label": "iOS source",
+			"description": "URL to the USDZ model for AR on iOS.",
+			"type": "string"
+		},
+		"arButtonText": {
+			"label": "AR button text",
+			"description": "Custom text for the AR button.",
+			"type": "string"
+		},
+		"loadingText": {
+			"label": "Loading text",
+			"description": "Custom text to display while loading.",
+			"type": "string"
+		},
+		"errorText": {
+			"label": "Error text",
+			"description": "Custom text to display if loading fails.",
+			"type": "string"
+		}
+	}
+}
+</templatedata>
+</noinclude>