Extensible 3D (X3D)
Part 1: Architecture and base components

Annex L

(informative)

HTML authoring guidelines

# L.1 Introduction and table of contents

This annex describes basic X3D scene integration within an HTML page and provides guidelines for X3D browser implementers when targeting HTML environments [W3C-HTML5]. These recommended practices are intended to encourage use of X3D models compatibly with HTML pages when used in a single Web X3D browser.

Table L.1 lists the major topics in this annex.

Table L.1 — Topics

L.1 Introduction and table of contents L.2 X3D implementations in HTMLX3Dbrowsers L.3 Page integration L.3.1 Content definition and page presentation L.3.2 Syntax, capitalization and validation L.3.3 Use of idattribute definitions L.3.4 Cascading Style Sheets (CSS) considerations L.3.5 Cross-Origin Resource Sharing (CORS) considerations L.4 Event handling, focus and interaction L.4.1 HTML and X3D synchronization L.4.2 JavaScript/ECMAScript considerations L.4.3 User focus considerations Figure L.1 — Example HTML X3D Rendering Synchronization and Event-Passing Connections Table L.1 Topics

# L.2 X3D implementations in HTML X3D browsers

The Hypertext Markup Language (HTML) is the World Wide Web’s core markup language. HTML is a general description language for documents and online applications [W3C-HTML5]. As part of HTML, the Document Object Model (DOM) defines a string-based node tree for representing HTML or XML documents, and also defines event-based processing methods that can be implemented by multiple programming languages [W3C-DOM] [W3C-HTML5].

This document specifies a general-purpose architecture for publishing and sharing 3D graphics models. Since X3D utilizes Web standards and includes an XML file encoding, it is well suited for integration in HTML pages over the World Wide Web.

The X3D design supports multiple goals related to use with HTML/DOM:

- X3D models are specified as a "first-class media type" similar to other image, audio and video formats.
- Event models are harmonized so that DOM events such as user interaction within the HTML page can also affect the X3D model, and vice versa.
- Standards compliance is encouraged wherever possible while also enabling ongoing interaction and interoperability improvements.
- Usage of multiple file encodings is allowed. For example, a url address for an X3D model might point to XML, ClassicVRML, JSON, or another file encoding.
- One or more distinct X3D scenes are allowed to be be loaded at one time within an HTML page.
- HTML page-integration patterns specified for Scalable Vector Graphics (SVG) [W3C-SVG] are consistently followed.

These general guidelines for X3D model display and interaction as part of Web-page presentations allow continuing innovation and adaptability.

# L.3 Page integration

## L.3.1 Content definition and page presentation

There are two basic approaches to loading X3D models within HTML pages:

- Including X3D model elements within an HTML page, or else
- Referencing an external X3D model in an HTML page media element.

For X3D elements appearing within HTML document source, the HTML/DOM id attribute can be used for selecting X3D model elements using HTML-page Script nodes (as can any other HTML selector such as CSS). Such node identification is similar to the use of DEF when X3D events are passed by a ROUTE connection, allowing disambiguation of specific node instances when needed.

There are also two basic approaches for the visual presentation of X3D models: either

- Reserve a dedicated rectangular canvas (similar to historic EMBED element), or else
- Float above/below other layers of content on the HTML page.

X3D Background transparency field allows HTML layer(s) beneath an X3D model to be visible (whether floating or fixed). This capability can support special layouts for page composition.

Each approach is expected to follow [W3C-HTML5] and [W3C-DOM] rules for page composition, and X3D rules for scene presentation.

## L.3.2 Syntax, capitalization and validation

HTML has two syntax definitions: HTML syntax (mixed case, some restrictions on self-closing tags) and XHTML syntax (CamelCase capitalization, well-formed XML elements).

The capitalization of X3D elements and attributes shall match the allowed syntax of HTML where they appear, matching case conventions for a given HTML or XHTML syntax.

X3D model validation according to schema, DOCTYPE or other mechanisms typically requires strict compliance to upper/lower case name definitions in this document .

## L.3.3 Use of id attribute definitions

The reserved id attribute on each X3D node can be considered a unique identifier when used as part of an encompassing HTML/DOM context. Any id identifiers are in a distinct separate namespace from X3D DEF identifiers and thus are not applicable for USE nodes, ROUTE statements, or Script references.

## L.3.4 Cascading Style Sheets (CSS) considerations

Cascading Style Sheets (CSS) is a language for describing the rendering of structured documents (such as HTML and XML) on various display surfaces including screen and paper. CSS is a core language for the World Wide Web that is commonly used for separation of content and presentation, improving layout flexibility.

Design goals for using CSS with X3D include achieving levels of functionality similar to that which exists for using CSS with HTML.

CSS comprises multiple specifications listed in the latest version of CSS Snapshot Recommendation [W3C-CSS-Snapshot]. CSS can be applied and used for Web pages using HTML syntax or XHTML syntax [W3C-HTML5], Scalable Vector Graphics (SVG) [W3C-SVG], and Extensible Markup Language (XML) [W3C-XML] documents, such as models defined using the X3D XML encoding in ISO/IEC 19776-1.

The reserved class attribute on each X3D node can provide a space-separated list of classes that pertain from associated stylesheets.

The reserved style attribute on each X3D node permits direct definition of style information, rather than referring to styles defined in a separate document [W3C-CSS-Style] [W3C-CSS-Snapshot].

CSS styling of X3D models follows the specific styling of the parent media element on the HTML page.

The CSS style attribute is not used to override the FontStyle/ScreenFontStyle style field, which is reserved for native X3D style definitions. Instead the parent Text node's CSS style attribute can be used to override FontStyle/ScreenFontStyle styling, if appropriate and supported.

## L.3.5 Cross-Origin Resource Sharing (CORS) considerations

Cross-origin resource sharing (CORS) "is a mechanism that allows restricted resources on a web page to be requested from another domain, outside the domain from which the first resource was served."

"CORS defines a way in which a X3D browser and server can interact to determine whether it is safe to allow the cross-origin request." HTML Web X3D browser limitations may similarly restrict loading remote content (such as an JavaScript X3D browser) from a remote system. Restrictions apply for any combination of locally served content and remotely served content, including local file system.

Details regarding CORS operation by a Web X3D browser are specified in [WHATWG-Fetch].

# L.4 Event handling, user focus and interaction

## L.4.1 HTML and X3D synchronization

An example approach to HTML X3D Event-Passing Connections is shown in Figure L.1, Example HTML X3D Rendering Synchronization and Event-Passing Connections. This diagram illustrates potential timing and synchronization for rendering of an HTML page and an X3D model, with possibility of event passing between them. It is important to achieve repeatable behavior and efficient rendering with interactive response to user focus.

These relationships are conceptual and not necessarily indicative of any individual implementation, in a manner similar to Figure 4.1 — X3D architecture and Figure 4.3 — Conceptual execution model. Multiple design variations are permitted for HTML-X3D implementations as long as the functional requirements of relevant HTML and X3D specifications are met.

Figure L.1 — Example HTML X3D Rendering Synchronization and Event-Passing Connections

Shared HTML events and X3D events (if available) are sent and received at end of each respective render cycle. Once initiated, an X3D event cascade proceeds to completion before any further external events are exchanged (see 4.4.8.3 Execution model). Available X3D events are shared with the HTML engine via mechanisms such as dispatching a custom HTML event, or invoking an author-defined callback.

Note that both HTML and X3D specifications include definitions for a Script node, so disambiguation is necessary. One possible approach is to require that X3D Script nodes can only appear between X3D elements within an HTML page, and HTML Script nodes are forbidden from appearing between X3D elements. An alternative approach is that any X3D Script node located within HTML page might be renamed X3DScript to avoid any node naming collisions.

## L.4.2 JavaScript/ECMAScript considerations

JavaScript is a programming language that conforms to the ECMAScript specification. The names are often used interchangeably, with ECMAScript indicating strictly specified formal definitions (see ISO/IEC 16262 Information technology — ECMAScript language specification).

Specified ECMAScript Application Programming Interface (API) capabilities for X3D Script node are defined functionally and syntactically in ISO/IEC 19775-2 X3D Scene Authoring Interface (SAI) and ISO/IEC 19776-1 — X3D ECMAScript encoding, respectively.

X3D browser implementations and language versions for JavaScript/ECMAScript engines can vary. Since X3D SAI functional requirements are carefully scoped to match the essential capabilities of this core Web programming language, a single JavaScript/ECMAScript engine can typically be used for both HTML and X3D event handling.

Within a Web X3D browser, implementations for HTML and X3D may share a single JavaScript/ECMAScript engine. Such integration is often important for both performance and synchronization issues. This consideration is especially important when considering the demanding response-time requirements of immersive interfaces and spatial body-tracking devices. To aid portability and avoid unintended overloading of variable references, it is good practice for X3D Script authors to avoid the use of variables with global scope.

## L.4.3 User focus considerations

User focus of attention refers to which part of an HTML page is receiving user-directed events such as selection, dragging, and text input. Such capturing of events for callback handling may seem simple but nevertheless can become quite sophisticated, and multiple approaches may be necessary since both displays and device interfaces can vary widely.

X3D provides a consistent selection and navigation interface across a wide range of devices that is based on platform-neutral definitions for model interaction. Suggested device mappings providing consistent user semantics are defined in Annex G Recommended navigation behaviours. Such flexibility is especially important when designing model displays and interactions that support user accessibility.

Web X3D browsers implementing HTML pay close attention to user focus according to [W3C-HTML5] and correspondingly direct user-driven events to appropriate sections of the document graph through the DOM [W3C-DOM]. These are the governing references regarding disposition of events according to user focus prior to receipt by the X3D render engine.

Of interest is that X3D scenes can include Background transparency field that may reveal underlying HTML content unobscured by geometry. X3D browsers may optionally pass user-driven events back to the underlying page layers for further HTML/DOM processing.