diff --git a/assets/rivs/webdocgraphics.riv b/assets/rivs/webdocgraphics.riv new file mode 100644 index 00000000..c4ac3f23 Binary files /dev/null and b/assets/rivs/webdocgraphics.riv differ diff --git a/docs.json b/docs.json index 64cb426d..696fe39f 100644 --- a/docs.json +++ b/docs.json @@ -204,6 +204,7 @@ "editor/data-binding/lists" ] }, + "editor/data-binding/binding-data", "editor/data-binding/converters", "editor/data-binding/controlling-data", "editor/data-binding/property-groups", diff --git a/editor/data-binding/binding-data.mdx b/editor/data-binding/binding-data.mdx new file mode 100644 index 00000000..f79f68f8 --- /dev/null +++ b/editor/data-binding/binding-data.mdx @@ -0,0 +1,148 @@ +--- +title: "Binding Data" +description: "Binding is how you connect data to properties and elements in your Rive file." +--- + +import { YouTube } from '/snippets/youtube.mdx' +import { UseCase } from '/snippets/use-case.mdx' + +For example, if you have a `teamName` property bound to a text run in your scene, changing the `teamName` value updates the displayed text automatically. + +You can change property values in the editor or at runtime, allowing you to create dynamic experiences that adapt to each user. + +Bindings are not limited to visual properties. You can bind values throughout your file, including transforms, animation speeds, [converter values](/editor/data-binding/converters#converter-types), [script inputs](/scripting/script-inputs#data-binding-inputs), [transition condition values](/editor/state-machine/transitions), and more. + +This allows the same data to drive behavior, animation, and logic across your scene, helping keep everything in sync. + +## Binding a Property + +Let's control the `X` position of a circle using `circleX`, which is a Number property in our View Model. + +![Bind a property](/images/editor/data-binding/binding-data/bind-value.gif) + + + + With your circle selected, right-click the `X` field, and select **Data Bind**. + + + In the **Property** dropdown, select `circleX`. + + + +The `X` field should now be highlighted in green, indicating that it's bound to a value. + +The circle's horizontal position is now driven by the `circleX` property. Any time the property's value changes, the circle updates automatically. + +![Bind a property](/images/editor/data-binding/binding-data/updating-values.gif) + + + If the field has a yellow border, there is a problem with the binding. + + In most cases, the property type is incompatible with the target value. For example, the `X` position of an element can only be bound to a Number property. + + + + **Previewing Bindings** + + By default, your data only controls your elements when the state machine is playing. + + To preview your data-bound values, turn on the **Data Binding Preview Toggle**. + + ![Preview data binding](/images/editor/data-binding/binding-data/preview-data-binding.gif) + + +### Updating a Binding + +Right-click the bound element and select **Update Bind**. + +![Update a binding](/images/editor/data-binding/binding-data/update-bind.gif) + +### Removing a Binding + +Right-click the bound element and select **Unbind**. + +![Remove a binding](/images/editor/data-binding/binding-data/unbind.gif) + +## Binding Options + +Each binding has the following properties. + +### Property + +The View Model property the target is connected to. + +![Property field](/images/editor/data-binding/binding-data/property.png) + +### Path + +When binding to 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 + +By default, the View Model property (**source**) controls the bound element or value (**target**), but it can also work the other way around. + + + +#### Target to Source + +When a binding has `Target to Source` toggled on, a change to the element will update the view model property. + +![Target to source](/images/editor/data-binding/binding-data/target-to-source.png) + + + Let's say you have a walk cycle animation and you want to track the exact Y position of the head as it bobs up and down. + + With the head's `Y` position bound to `headY` using **Target to Source**, the `headY` property updates automatically as the head moves. + + +#### Bidirectional + +A change to the view model property will update the element **AND** a change to the element will update the view model property. + +![Bidirectional data binding](/images/editor/data-binding/binding-data/bidirectional.gif) + +Clicking the **Bidirectional** toggle multiple times will cycle between **Bidirectional (prefer target value)** and **Bidirectional (prefer source value)**. + +In rare cases, both the source and target may change at the same time. This setting determines which value wins when a conflict occurs. + + + Let's say you're building a game of checkers and need to create logic for dragging and dropping each piece. + + The initial position of each piece is determined by the `piecePositionX` and `piecePositionY` properties (source to target). + + As the piece is dragged, the piece itself (target) updates those property values (target to source). + + +### Bind Once + +When **Bind Once** is enabled, the binding only applies the value a single time when the scene starts or the binding is created. + +![Bind once](/images/editor/data-binding/binding-data/bind-once.png) + +After the initial value is applied, future changes to the source or target are ignored. + + + Let's say you're creating a particle effect and want each particle to start with a random rotation value. + + You could bind the particle's rotation to a random number property using **Bind Once**. Each particle would receive its initial rotation value, but future changes to the property would not affect existing particles. + + +### Absolute vs Relative Binding + + + +By default, new data binding connections are created as absolute binds. + +- **Absolute Binding**: The binding points to a specific property instance within the View Model hierarchy. +- **Relative Binding**: The binding searches for a property with a matching name relative to the current context. + diff --git a/editor/data-binding/converters.mdx b/editor/data-binding/converters.mdx index 276045eb..b7f54d01 100644 --- a/editor/data-binding/converters.mdx +++ b/editor/data-binding/converters.mdx @@ -35,6 +35,10 @@ Use them to adapt your data to match the property you're binding to—for exampl Converters can be used individually or combined into [groups](#converter-groups) to perform more complex transformations. +Each converter has its own set of properties, many of which can be bound to other View Model properties. +This allows converter behavior to update dynamically. For example, you could bind the maximum value of a range map, a multiplier in a formula, or the padding amount in a string converter. + + | Category | Converter | Description | |----------|--------------------------|-------------------------------------------| | String | [Pad](#pad) | Add padding to a string | @@ -192,5 +196,3 @@ Converters run from top to bottom: Drag a converter up or down to change when it runs. Earlier converters affect all converters that follow. - - diff --git a/editor/data-binding/overview.mdx b/editor/data-binding/overview.mdx index 885912b3..442f860e 100644 --- a/editor/data-binding/overview.mdx +++ b/editor/data-binding/overview.mdx @@ -56,31 +56,3 @@ Artboards are assigned an instance to populate the data bindings. Changing which In order for an instance to be visible to developers, it must be marked as Exported. Otherwise, it is considered internal to the file. One reason you may want to keep it internal is if you only use the instance to test your design when it is configured with a given set of values, including edge cases. These exported instances can then be assigned to an artboard at runtime by developers. Alternatively, developers can create empty instances which have default values, such as zero for numbers and empty strings. Once the instance is assigned, its values will begin updating according to the bindings. - -### Binding - -A binding is an association between a view model property and an editor element. For instance, you might have a string property called "name" bound to a text run. Once bound, the text run will take the value from the view model property. See [Bind Direction](#bind-direction) for additional options. - -#### Absolute & Relative Binding -By default, new data binding connections are created as absolute binds. - -- Absolute Binding: the bind points the value at a specific property location within the view model tree. For example, "the second property of the first view model". -- Relative Binding: the bind finds the value of property with a specific name, regardless of where it falls within the view model tree. For example, a relative binding to "myNumber" will look for a property of that name within the view model available. - - - -#### Bind Direction - -Bindings can be source to target, target to source, or bidirectional. In this case, "source" means the property, and "target" means the editor element. - - - -The default binding is source to target. This means that changes to the property update the value of the element. For example, an XPos property updates the X position of an object. - -Target to source means that changes to the element's value update the property. For example, the X position of an object updates the XPos property. - -Bidirectional means that changes are applied in both directions, meaning either the element or the property can update the other. - -Additionally, a binding may be marked as "Bind Once". This means that the initial value will apply and thereafter the binding will not apply any updates. - - diff --git a/images/editor/data-binding/binding-data/bidirectional.gif b/images/editor/data-binding/binding-data/bidirectional.gif new file mode 100644 index 00000000..52a99cdc Binary files /dev/null and b/images/editor/data-binding/binding-data/bidirectional.gif differ diff --git a/images/editor/data-binding/binding-data/bind-once.png b/images/editor/data-binding/binding-data/bind-once.png new file mode 100644 index 00000000..e3b977d4 Binary files /dev/null and b/images/editor/data-binding/binding-data/bind-once.png differ diff --git a/images/editor/data-binding/binding-data/bind-value.gif b/images/editor/data-binding/binding-data/bind-value.gif new file mode 100644 index 00000000..93ce5f94 Binary files /dev/null and b/images/editor/data-binding/binding-data/bind-value.gif differ diff --git a/images/editor/data-binding/binding-data/convert.png b/images/editor/data-binding/binding-data/convert.png new file mode 100644 index 00000000..b70540ac Binary files /dev/null and b/images/editor/data-binding/binding-data/convert.png differ diff --git a/images/editor/data-binding/binding-data/path.gif b/images/editor/data-binding/binding-data/path.gif new file mode 100644 index 00000000..944e1da8 Binary files /dev/null and b/images/editor/data-binding/binding-data/path.gif differ diff --git a/images/editor/data-binding/binding-data/preview-data-binding.gif b/images/editor/data-binding/binding-data/preview-data-binding.gif new file mode 100644 index 00000000..aaf84f62 Binary files /dev/null and b/images/editor/data-binding/binding-data/preview-data-binding.gif differ diff --git a/images/editor/data-binding/binding-data/property.png b/images/editor/data-binding/binding-data/property.png new file mode 100644 index 00000000..96937156 Binary files /dev/null and b/images/editor/data-binding/binding-data/property.png differ diff --git a/images/editor/data-binding/binding-data/target-to-source.png b/images/editor/data-binding/binding-data/target-to-source.png new file mode 100644 index 00000000..d9b002b7 Binary files /dev/null and b/images/editor/data-binding/binding-data/target-to-source.png differ diff --git a/images/editor/data-binding/binding-data/unbind.gif b/images/editor/data-binding/binding-data/unbind.gif new file mode 100644 index 00000000..6178ffec Binary files /dev/null and b/images/editor/data-binding/binding-data/unbind.gif differ diff --git a/images/editor/data-binding/binding-data/update-bind.gif b/images/editor/data-binding/binding-data/update-bind.gif new file mode 100644 index 00000000..b22ac280 Binary files /dev/null and b/images/editor/data-binding/binding-data/update-bind.gif differ diff --git a/images/editor/data-binding/binding-data/updating-values.gif b/images/editor/data-binding/binding-data/updating-values.gif new file mode 100644 index 00000000..4da50b0a Binary files /dev/null and b/images/editor/data-binding/binding-data/updating-values.gif differ diff --git a/snippets/rive-card.jsx b/snippets/rive-card.jsx deleted file mode 100644 index b498c653..00000000 --- a/snippets/rive-card.jsx +++ /dev/null @@ -1,81 +0,0 @@ -export const RiveCard = ({ title, description, links, children, source }) => { - - const runtimesInOrder = ['web', 'react', 'reactNative', 'flutter', 'apple', 'android', 'unity', 'unreal'] - const runtimeTitles = { - web: 'Web', - react: 'React', - reactNative: "React Native", - flutter: 'Flutter', - apple: 'Apple', - android: 'Android', - unity: 'Unity', - unreal: 'Unreal' - } - - const RuntimeLink = ({ link, runtime }) => { - if (!link) return null - - return ( - - {runtimeTitles[runtime]} - - ) - } - - return ( -
- -
-
- { children } -
-
- -
-
-

{title}

-
-
-

{description}

- { - source && source.length > 0 && ( -

- { - source.map((item, index) => { - if (source.length == 1) { - return <>Open the Rive file. - } - - if (index == 0) { - return <>Open Rive file 1 - } - - return <>, file {index + 1} - }) - } -

- ) - } -
-
- { - runtimesInOrder.map((currentRuntime) => { - return ( - - ) - }) - } -
-
-
-
-
- ) - -}; diff --git a/snippets/use-case.mdx b/snippets/use-case.mdx new file mode 100644 index 00000000..85906360 --- /dev/null +++ b/snippets/use-case.mdx @@ -0,0 +1,14 @@ +export const UseCase = ({ title, children }) => { + return ( + + ); +};