feat(docs): add apple experimental api #393
Conversation
|  | ||
|
|
||
| ## Getting Started | ||
| ## The Two Apple APIs |
There was a problem hiding this comment.
I'd say not to advertise "two" Apple APIs. This gives the impression that we will continue to support both long term and reading this makes me question which API I should use, and we should answer that clearly at the start.
I'd rather just add a or something at the top that gives this information in a few sentences. For example: "The new Rive Apple runtime is available in technical preview. Check it out and give us feedback. If you're starting a new project in Rive we recommend using the new API - but note it's still in technical preview and might change."
We could also add a note to say that eventually the old API will be deprecated and removed. It's now in maintenance mode.
All of the other technical information can then be moved to the getting started tabs. TLDR; make the decision easy to use the new API.
| ``` | ||
| </Step> | ||
| <Step title="v2 Runtime Usage"> | ||
| It is important to note that while this new API support multi-threading, the calls to the Rive API must still be made on the main thread. This is enforced at compile time by marking functions and types as `@MainActor`. |
There was a problem hiding this comment.
This info could rather be a subsection in the getting started, with a header "Threading" that gives all the threading/worker info
| It is recommended to begin using the new API in new projects and provide feedback, and to investigate migrating existing projects to the new API when feasible. | ||
|
|
||
| **Set up RiveViewModel w/ View** | ||
| ### The Current API |
There was a problem hiding this comment.
I know we chatted about a few options. But I'd mark this a "Legacy" already. That is what Android and React Native is already doing.
- New API (Experimental)
- Legacy API
There was a problem hiding this comment.
Ah I see you did that in the tab.
| </Note> | ||
|
|
||
| <Tabs> | ||
| <Tab title="From File"> |
There was a problem hiding this comment.
Instead of a Tab, these can be those coded tabs (I forget the name), as it's only code.
There was a problem hiding this comment.
Same for other areas. But this is just an idea.
| </Tab> | ||
| </Tabs> | ||
| </Step> | ||
| <Step title="Advanced Usage"> |
There was a problem hiding this comment.
We should add a step before that describes data binding. It's a incredibly important runtime feature. We should shove it in people faces and not assume they will actually read the additional linked docs.
HayesGordon
left a comment
HayesGordon
left a comment
There was a problem hiding this comment.
Overall looks great, some suggestions on restructuring the main page and highlighting a few things. The other main thing is to avoid writing the new runtime code as migration - we should optimize for people who don't care about the old API, and for those that do care we will have a migration guide.
| </Tabs> | ||
| </Step> | ||
| <Step title="Advanced Usage"> | ||
| For information on the new `Artboard` type and API, see [Artboards](/runtimes/artboards.mdx). |
There was a problem hiding this comment.
If you wanted to be fancy you could make these cards
| </Tab> | ||
| </Tabs> | ||
|
|
||
| ## Enabling Logging |
There was a problem hiding this comment.
For all these section I would already create a tab for the different API. And for the new one say that support is planned
|
|
||
| For information on the new `StateMachine` type and API, see [State Machine Playback](/runtimes/state-machines.mdx). | ||
|
|
||
| For information on the new Data Binding APIs, see [Data Binding](/runtimes/data-binding.mdx). |
There was a problem hiding this comment.
Might have missed it, but let's clearly call out the example app code for the new runtime api
| ``` | ||
| </Step> | ||
| <Step title="Add a View"> | ||
| Once you have created a `File`, you can move onto creating a `Rive` object. This object defines the configuration of a view. The most basic implementation is created with just a file; Rive will handle loading the correct artboard and state machine for rendering. |
There was a problem hiding this comment.
Instead of "correct", let's say "default, as set in the Rive Editor". Correct implies that there is some magic.
|
|
||
| ### Using an Artboard | ||
|
|
||
| Remember that the Rive configuration for a view is the `Rive` type. In the overview, we show initializing a `Rive` object with just a file. However, you can initialize a `Rive` object with a specific artboard: |
There was a problem hiding this comment.
"object with just a file" is misleading to me. Let's rather explain that these are optional parameters. If you don't supply an artboard we will create the default artboard automatically.
| ```swift | ||
| simpleVM.play() | ||
| ``` | ||
| Remember that the Rive configuration for a view is the `Rive` type. In the overview, we show initializing a `Rive` object with just a file. However, you can initialize a `Rive` object with a specific state machine: |
There was a problem hiding this comment.
Same comments as before. Let's say we will create the defaults if not supplied.
| override public func loadView() { | ||
| super.loadView() | ||
| Once you have created a `File`, you can then retrieve information for and create `Artboard` types. |
There was a problem hiding this comment.
This should be created an Artboard and create a StateMachine
|
|
||
| // Data binding view model by name | ||
| let viewModelByName = file.viewModelNamed("...") | ||
| There are currently two options: |
There was a problem hiding this comment.
You should say where these options come from.
| print(numberProperty.value) | ||
| <Tabs> | ||
| <Tab title={Apple.currentRuntimeName}> | ||
| Contrary to the {Apple.legacyRuntimeName} API, properties are not reference types; instead, they are a very thin wrapper around the path and return type of a property. |
There was a problem hiding this comment.
Might want to avoid comparing the runtimes here. This is better reserved for a migration guide. Someone new reading this won't care
| let riveViewModel = RiveViewModel(...) | ||
| <Tabs> | ||
| <Tab title={Apple.currentRuntimeName}> | ||
| Property listeners now utilize Swift Concurrency's async throwing streams. |
There was a problem hiding this comment.
Same, this reads like a migration. One way to think about these new docs is that it should be sensible without needing to know the old runtime. Ideally in the future we can just remove the old runtime tab and keep all this exactly the same when we remove the old runtime
No description provided.