diff --git a/editor/data-binding/binding-data.mdx b/editor/data-binding/binding-data.mdx index f79f68f8..2e3fa67b 100644 --- a/editor/data-binding/binding-data.mdx +++ b/editor/data-binding/binding-data.mdx @@ -73,14 +73,20 @@ The View Model property the target is connected to. ![Property field](/images/editor/data-binding/binding-data/property.png) + + When binding global properties, select the **Globals** icon. + ![Select the Globals icon](/images/editor/data-binding/binding-data/global-properties.gif) + + ### Path -When binding to nested View Models, there may be multiple properties with the same name available. +When binding properties in nested View Models, there may be multiple properties with the same name available. The path determines which specific property instance the binding should use. ![Preview data binding](/images/editor/data-binding/binding-data/path.gif) + See also [Absolute vs Relative Binding](#absolute-vs-relative-binding). ### Bind Direction diff --git a/editor/data-binding/view-models.mdx b/editor/data-binding/view-models.mdx index 22048cdf..bf0d1b25 100644 --- a/editor/data-binding/view-models.mdx +++ b/editor/data-binding/view-models.mdx @@ -46,17 +46,18 @@ A View Model defines the structure of your data. Before creating View Model Inst New Rive files come with a default view model called "ViewModel1" that is already attached to the main artboard. -![Create a View Model](/images/editor/data-binding/view-models/create-view-model.gif) - In the Data panel Click the `+` icon and select **View Model**. + In the Data panel, click the `+` icon and select **View Model** or [**Global View Model**](#global-view-model-instances). In the Data panel, click the **Add View Model Property** button next to the view model name and select your [property type](/editor/data-binding/property-types). +![Create a View Model](/images/editor/data-binding/view-models/create-view-model.gif) + ## Creating and Editing Instances Once your View Model has been created, you can create one or more View Model Instances that store actual values for those properties. @@ -120,34 +121,39 @@ By default, exported View Model Instances are included in the .riv file. Disable Before binding data, you'll need to decide where the data should live. -Rive supports three common patterns: +Rive supports a few common patterns: | Pattern | | | :------------- | :----------- | -| [Top-Level Instance](#top-level-artboard-view-model-instances) | The data lives on the top-level artboard and its values can be used throughout the Rive file | -| [Nested components](#nested-component-instances) | The parent view model instance stores a reference to a nested view model instance, which can be applied to a nested component | +| [Global Instances](#global-view-model-instances) | Global view models and their properties are directly accessible to all artboards | +| [Instances attached to artboards](#instances-attached-to-artboards) | The view model instance is attached to the artboard and its values can be used by that artboard and its children | +| [Instances as nested properties](#instances-as-nested-properties) | The parent view model instance stores a reference to a nested view model instance | | [Stateful nested components](#stateful-components) | Self-contained, reusable components that store their own unique data | -### Top-Level Artboard View Model Instances +### Global View Model Instances + +Global view models are not connected to a specific artboard. Instead, the view model instance and its properties are directly accessible to all artboards. + + +A game's main view model might contain a `brandColor` or `score` property. This property might be used by various nested components, like the header, on buttons, or on a high scores screen. + + +### Instances Attached to Artboards -Attach a View Model Instance directly to the top-level artboard when the data should be available to the entire artboard and its children. +View Model instances can be attached to a specific artboard or nested component. This is useful when only that artboard and its children need access to that data. ``` -GameVM +EnemyVM ├─ health -└─ score -└─ avatar ``` -![Main VM](/images/editor/data-binding/view-models/main-vm.png) - -A game's main view model might contain a score property. This property might be used by various nested components, like the header and within the high scores modal. +An Enemy view model might contain a `health` property. This property might be used by the enemy itself, but not by its parent. -### Nested Component Instances +### Instances as Nested Properties -Components can also have their own View Model Instances. +View Models can have properties that are View Model instances. In this pattern, the parent View Model stores references to child instances, either directly or through a [list](/editor/data-binding/lists). @@ -164,8 +170,6 @@ InventoryVM └─ Potion ``` -Each component instance can have its own view model instance attached to it. - ![Attach instance to component](/images/editor/data-binding/view-models/connect-instance-to-nested-component.png) This approach is useful when a parent artboard needs to manage a collection of items while still allowing each component to maintain its own data. @@ -174,8 +178,6 @@ This approach is useful when a parent artboard needs to manage a collection of i An inventory screen might contain a list of Item View Model Instances, with each inventory slot component bound to a different item. -Because each instance must be created and connected explicitly, this pattern provides strong runtime control at the cost of additional setup. - ### Stateful Components A stateful component is an instance of a component that maintains its own data. diff --git a/images/editor/data-binding/binding-data/global-properties.gif b/images/editor/data-binding/binding-data/global-properties.gif new file mode 100644 index 00000000..1bc1e260 Binary files /dev/null and b/images/editor/data-binding/binding-data/global-properties.gif differ diff --git a/images/editor/data-binding/view-models/main-vm.png b/images/editor/data-binding/view-models/main-vm.png deleted file mode 100644 index fa32a5b3..00000000 Binary files a/images/editor/data-binding/view-models/main-vm.png and /dev/null differ