diff --git a/ModuleClientAPI.md b/ModuleClientAPI.md index cebc997..a0c7ef5 100644 --- a/ModuleClientAPI.md +++ b/ModuleClientAPI.md @@ -1,129 +1,4 @@ -# ModuleClientAPI - -## Introductions - -The **ModuleClientAPI** is the heart of every interactive Getiyo module's front-end experience. When users visit your channel and see your module in action, they're interacting with code powered by this comprehensive client-side interface. Think of it as your module's direct connection to the Getiyo ecosystem—enabling real-time communication with your server-side logic, responding instantly to property changes from the editor, and creating seamless user experiences that feel native to the platform. - -### What Makes ModuleClientAPI Essential - -Every Getiyo module consists of two primary components: server-side logic that handles data processing and business rules, and client-side presentation that users actually see and interact with. The ModuleClientAPI bridges these two worlds, automatically establishing a persistent connection between your module's user interface and its corresponding [`ModuleServerAPI`](./ModuleServerAPI). This connection enables the real-time interactivity that makes Getiyo modules feel alive and responsive. - -When you develop a module's user page, the ModuleClientAPI is automatically available as a global `api` object. This isn't just a simple communication tool—it's a comprehensive interface that understands Getiyo's unique architecture of scenes, displays, properties, and user management. Unlike traditional web development where you might manually handle WebSocket connections or polling for updates, the ModuleClientAPI abstracts away these complexities while providing powerful features specifically designed for Getiyo's live, collaborative environment. - -### Real-Time Property Updates - -One of the most powerful features of the ModuleClientAPI is its ability to receive live property updates through [`api.onPropertyUpdate()`](./ModuleClientAPI#onpropertyupdate). When someone editing a scene changes a color, updates text, or modifies any reference property of your module, those changes flow instantly to all connected viewers without requiring module redeployment or page refreshes. This creates an incredibly smooth content creation workflow where editors can see their changes reflected immediately across all displays. - -This real-time capability extends beyond simple property updates. The ModuleClientAPI automatically handles the complexity of managing multiple module instances, ensuring that property updates reach the correct module references even when the same module type appears multiple times in a single scene. Your code simply registers listeners for the properties it cares about, and the API handles all the routing and synchronization behind the scenes. - -### Seamless Communication - -Communication between your module's client and server components flows through intuitive message-passing methods. The [`api.send()`](./ModuleClientAPI#send) function allows you to transmit any data to your server-side code, while [`api.on()`](./ModuleClientAPI#on) lets you listen for responses or server-initiated messages. This bidirectional communication happens over persistent connections that the API manages automatically, including reconnection handling and message queuing during temporary network interruptions. - -The communication system also supports interaction between neighboring modules through [`api.onNeighborMessage()`](./ModuleClientAPI#onneighbormessage) and [`api.getNeighbors()`](./ModuleClientAPI#getneighbors). This enables sophisticated module ecosystems where different components can coordinate their behavior, share state, or trigger cascading effects across a scene. - -### User-Centric Design - -Getiyo's strength lies in its understanding that every viewer is a unique user with specific capabilities, preferences, and context. The ModuleClientAPI provides deep integration with Getiyo's user management system through [`api.getUser()`](./ModuleClientAPI#getuser). Your module can access user details, check device capabilities, and adapt its interface accordingly—whether someone is viewing on a mobile device, has specific accessibility needs, or belongs to a particular organization. - -The user integration goes beyond simple profile access. Methods like [`api.getUser().getName()`](./ModuleClientAPIUser#getname) can automatically prompt users to enter their name if they haven't already, creating seamless onboarding experiences. Camera and microphone access, mobile device detection, and user preference management are all handled through consistent, reliable interfaces that respect Getiyo's privacy and permission models. - -### Module Scope and Safety - -Traditional web development often struggles with scope management when multiple components share a page. The ModuleClientAPI solves this elegantly by providing module-scoped access to DOM elements through [`api.dom()`](./ModuleClientAPI#dom). Instead of using `document.querySelector()` which might accidentally select elements from other modules, you always query within your module's specific container. This prevents conflicts and ensures your module remains self-contained and reusable. - -Similarly, instead of listening to global `window` resize events, you use [`api.onResize()`](./ModuleClientAPI#onresize) to receive notifications when your specific module changes size. This module-scoped approach extends throughout the API, ensuring that your code remains robust even in complex scenes with multiple active modules. - -#### CSS and Sass Development - -The module scoping philosophy extends to your styling approach as well. While Getiyo provides automatic isolation between modules, you must structure your HTML and CSS properly to take advantage of this system. This means you should **never write global CSS** that targets elements like `body`, `html`, `p`, or `h1` directly. - -Instead, you need to create a main container element in your module's HTML with a descriptive class name, then scope all your CSS and Sass to that container: - -```html - -
-

My Module Title

-
- -
-
-``` - -```scss -// ❌ NEVER do this - affects all modules globally -body { - font-family: Arial, sans-serif; -} - -h1 { - color: red; -} - -// ✅ ALWAYS scope to your module's container class -.my-awesome-module { - font-family: Arial, sans-serif; - - h1 { - color: red; - font-size: 24px; - } - - .content-area { - padding: 20px; - - .action-button { - background: blue; - color: white; - border: none; - padding: 10px 20px; - border-radius: 4px; - } - } -} -``` - -This scoping approach ensures that: - -- **Multiple module instances** can coexist without style conflicts -- **Different module types** won't interfere with each other's appearance -- **Global Getiyo styling** remains intact and functional -- **Module reusability** is maintained across different scenes and channels - -Remember that Getiyo provides global styling for module containers including backgrounds, filters, blending modes, borders, and padding. Your module's CSS should focus on the internal layout and styling of your content within your own container class, not these container-level properties that Getiyo manages automatically. - -### Timing and Synchronization - -Live experiences require precise timing coordination across multiple displays and users. The ModuleClientAPI provides server-synchronized time through [`api.getTime()`](./ModuleClientAPI#gettime), ensuring that time-based animations, countdowns, and coordinated actions happen simultaneously across all viewers regardless of their local clock settings or network latency. - -The API also includes sophisticated timing utilities through [`api.GameLib.Timing`](./ModuleClientAPI#gametiming), offering easing functions, animation helpers, and frame-based timing tools that integrate seamlessly with Getiyo's rendering pipeline. These tools enable smooth, professional animations that feel native to the platform while maintaining perfect synchronization across all connected displays. - -### Integration with Getiyo's Ecosystem - -The ModuleClientAPI doesn't exist in isolation—it's deeply integrated with Getiyo's broader ecosystem of cue lists, conditions, snapshots, and show control. Your module can participate in automated sequences by finishing client conditions with [`api.finishClientCondition()`](./ModuleClientAPI#finishclientcondition), respond to volume changes and play state updates, and maintain and recall states through the runtime storage system. - -Global utilities like [`ce`](./ModuleClientAPI#ce) for quick element creation, [`Feedback`](./ModuleClientAPI#feedback) for system-consistent notifications, and [`loading`](./ModuleClientAPI#loading) indicators ensure your module feels like a natural part of the Getiyo experience rather than a separate component. - -### Getting Started - -Every module automatically has access to the ModuleClientAPI through the global `api` object. Your journey typically begins with setting up property listeners and communication handlers: - -```javascript -// React to property changes from the editor -api.onPropertyUpdate('backgroundColor', (color) => { - api.dom().style.backgroundColor = color; -}); - -// Communicate with your server-side logic -api.send('userAction', { type: 'click' }); - -// Listen for server responses -api.on('updateDisplay', (data) => { - // Update your module's presentation -}); -``` - -The ModuleClientAPI transforms what could be complex, error-prone web development into an intuitive, powerful experience that lets you focus on creating engaging content rather than managing infrastructure. Whether you're building simple informational displays or complex interactive experiences, the API provides the foundation for professional, reliable modules that integrate seamlessly with Getiyo's live production environment. +# ModuleClientAPI - Main ## Sub Classes diff --git a/ModuleClientAPIIntroduction.md b/ModuleClientAPIIntroduction.md new file mode 100644 index 0000000..b4732c0 --- /dev/null +++ b/ModuleClientAPIIntroduction.md @@ -0,0 +1,124 @@ +# ModuleClientAPI - Introductions + +The **ModuleClientAPI** is the heart of every interactive Getiyo module's front-end experience. When users visit your channel and see your module in action, they're interacting with code powered by this comprehensive client-side interface. Think of it as your module's direct connection to the Getiyo ecosystem—enabling real-time communication with your server-side logic, responding instantly to property changes from the editor, and creating seamless user experiences that feel native to the platform. + +## What Makes ModuleClientAPI Essential + +Every Getiyo module consists of two primary components: server-side logic that handles data processing and business rules, and client-side presentation that users actually see and interact with. The ModuleClientAPI bridges these two worlds, automatically establishing a persistent connection between your module's user interface and its corresponding [`ModuleServerAPI`](./ModuleServerAPI). This connection enables the real-time interactivity that makes Getiyo modules feel alive and responsive. + +When you develop a module's user page, the ModuleClientAPI is automatically available as a global `api` object. This isn't just a simple communication tool—it's a comprehensive interface that understands Getiyo's unique architecture of scenes, displays, properties, and user management. Unlike traditional web development where you might manually handle WebSocket connections or polling for updates, the ModuleClientAPI abstracts away these complexities while providing powerful features specifically designed for Getiyo's live, collaborative environment. + +## Real-Time Property Updates + +One of the most powerful features of the ModuleClientAPI is its ability to receive live property updates through [`api.onPropertyUpdate()`](./ModuleClientAPI#onpropertyupdate). When someone editing a scene changes a color, updates text, or modifies any reference property of your module, those changes flow instantly to all connected viewers without requiring module redeployment or page refreshes. This creates an incredibly smooth content creation workflow where editors can see their changes reflected immediately across all displays. + +This real-time capability extends beyond simple property updates. The ModuleClientAPI automatically handles the complexity of managing multiple module instances, ensuring that property updates reach the correct module references even when the same module type appears multiple times in a single scene. Your code simply registers listeners for the properties it cares about, and the API handles all the routing and synchronization behind the scenes. + +## Seamless Communication + +Communication between your module's client and server components flows through intuitive message-passing methods. The [`api.send()`](./ModuleClientAPI#send) function allows you to transmit any data to your server-side code, while [`api.on()`](./ModuleClientAPI#on) lets you listen for responses or server-initiated messages. This bidirectional communication happens over persistent connections that the API manages automatically, including reconnection handling and message queuing during temporary network interruptions. + +The communication system also supports interaction between neighboring modules through [`api.onNeighborMessage()`](./ModuleClientAPI#onneighbormessage) and [`api.getNeighbors()`](./ModuleClientAPI#getneighbors). This enables sophisticated module ecosystems where different components can coordinate their behavior, share state, or trigger cascading effects across a scene. + +## User-Centric Design + +Getiyo's strength lies in its understanding that every viewer is a unique user with specific capabilities, preferences, and context. The ModuleClientAPI provides deep integration with Getiyo's user management system through [`api.getUser()`](./ModuleClientAPI#getuser). Your module can access user details, check device capabilities, and adapt its interface accordingly—whether someone is viewing on a mobile device, has specific accessibility needs, or belongs to a particular organization. + +The user integration goes beyond simple profile access. Methods like [`api.getUser().getName()`](./ModuleClientAPIUser#getname) can automatically prompt users to enter their name if they haven't already, creating seamless onboarding experiences. Camera and microphone access, mobile device detection, and user preference management are all handled through consistent, reliable interfaces that respect Getiyo's privacy and permission models. + +## Module Scope and Safety + +Traditional web development often struggles with scope management when multiple components share a page. The ModuleClientAPI solves this elegantly by providing module-scoped access to DOM elements through [`api.dom()`](./ModuleClientAPI#dom). Instead of using `document.querySelector()` which might accidentally select elements from other modules, you always query within your module's specific container. This prevents conflicts and ensures your module remains self-contained and reusable. + +Similarly, instead of listening to global `window` resize events, you use [`api.onResize()`](./ModuleClientAPI#onresize) to receive notifications when your specific module changes size. This module-scoped approach extends throughout the API, ensuring that your code remains robust even in complex scenes with multiple active modules. + +### CSS and Sass Development + +The module scoping philosophy extends to your styling approach as well. While Getiyo provides automatic isolation between modules, you must structure your HTML and CSS properly to take advantage of this system. This means you should **never write global CSS** that targets elements like `body`, `html`, `p`, or `h1` directly. + +Instead, you need to create a main container element in your module's HTML with a descriptive class name, then scope all your CSS and Sass to that container: + +```html + +
+

My Module Title

+
+ +
+
+``` + +```scss +// ❌ NEVER do this - affects all modules globally +body { + font-family: Arial, sans-serif; +} + +h1 { + color: red; +} + +// ✅ ALWAYS scope to your module's container class +.my-awesome-module { + font-family: Arial, sans-serif; + + h1 { + color: red; + font-size: 24px; + } + + .content-area { + padding: 20px; + + .action-button { + background: blue; + color: white; + border: none; + padding: 10px 20px; + border-radius: 4px; + } + } +} +``` + +This scoping approach ensures that: + +- **Multiple module instances** can coexist without style conflicts +- **Different module types** won't interfere with each other's appearance +- **Global Getiyo styling** remains intact and functional +- **Module reusability** is maintained across different scenes and channels + +Remember that Getiyo provides global styling for module containers including backgrounds, filters, blending modes, borders, and padding. Your module's CSS should focus on the internal layout and styling of your content within your own container class, not these container-level properties that Getiyo manages automatically. + +## Timing and Synchronization + +Live experiences require precise timing coordination across multiple displays and users. The ModuleClientAPI provides server-synchronized time through [`api.getTime()`](./ModuleClientAPI#gettime), ensuring that time-based animations, countdowns, and coordinated actions happen simultaneously across all viewers regardless of their local clock settings or network latency. + +The API also includes sophisticated timing utilities through [`api.GameLib.Timing`](./ModuleClientAPI#gametiming), offering easing functions, animation helpers, and frame-based timing tools that integrate seamlessly with Getiyo's rendering pipeline. These tools enable smooth, professional animations that feel native to the platform while maintaining perfect synchronization across all connected displays. + +## Integration with Getiyo's Ecosystem + +The ModuleClientAPI doesn't exist in isolation—it's deeply integrated with Getiyo's broader ecosystem of cue lists, conditions, snapshots, and show control. Your module can participate in automated sequences by finishing client conditions with [`api.finishClientCondition()`](./ModuleClientAPI#finishclientcondition), respond to volume changes and play state updates, and maintain and recall states through the runtime storage system. + +Global utilities like [`ce`](./ModuleClientAPI#ce) for quick element creation, [`Feedback`](./ModuleClientAPI#feedback) for system-consistent notifications, and [`loading`](./ModuleClientAPI#loading) indicators ensure your module feels like a natural part of the Getiyo experience rather than a separate component. + +## Getting Started + +Every module automatically has access to the ModuleClientAPI through the global `api` object. Your journey typically begins with setting up property listeners and communication handlers: + +```javascript +// React to property changes from the editor +api.onPropertyUpdate('backgroundColor', (color) => { + api.dom().style.backgroundColor = color; +}); + +// Communicate with your server-side logic +api.send('userAction', { type: 'click' }); + +// Listen for server responses +api.on('updateDisplay', (data) => { + // Update your module's presentation +}); +``` + +The ModuleClientAPI transforms what could be complex, error-prone web development into an intuitive, powerful experience that lets you focus on creating engaging content rather than managing infrastructure. Whether you're building simple informational displays or complex interactive experiences, the API provides the foundation for professional, reliable modules that integrate seamlessly with Getiyo's live production environment. diff --git a/_Sidebar.md b/_Sidebar.md index ba275bc..8c45b5e 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -12,16 +12,16 @@ - [Complete Example](./module.json) - [Development environment/Building](./ModuleEnvironment) - [GetiyoModuleTool](./GetiyoModuleTool) - - [ModuleClientAPI](./ModuleClientAPI) - - [Important Principals](./ModuleClientAPIPrincipals) + - [ModuleClientAPI](./ModuleClientAPIIntroduction) + - [Documentation](./ModuleClientAPI) - [User](./ModuleClientAPIUser) - [Neighbor](./ModuleClientAPINeighbor) - [Neighbor Results](./ModuleClientAPINeighborResults) - [GameLib](./ModuleClientAPIGameLib) - [Controller](./ModuleClientAPIGameLibController) + - [Important Principals](./ModuleClientAPIPrincipals) - [ModuleServerAPI](./ModuleServerAPI) - - [Important Principals](./ModuleServerAPIPrincipals) - [Client](./ModuleServerAPIClient) - [Property](./ModuleServerAPIProperty) - [GameLib](./ModuleServerAPIGameLib) @@ -32,6 +32,7 @@ - [Details](./ModuleServerAPIGameLibScoreboardDetails) - [State](./ModuleServerAPIGameLibScoreboardState) - [GameLib CollisionSpace](./ModuleServerAPIGameLibCollisionSpace) + - [Important Principals](./ModuleServerAPIPrincipals) - [Libs](./ModuleServerAPILibs) - [LibWebSocket](./ModuleServerAPILibsWebSocketLib) - [Axios](https://axios-http.com/docs/instance)