Mirrors/dioxus
2
0
Fork 0
mirror of https://github.com/DioxusLabs/dioxus synced 2024-11-23 04:33:06 +00:00
Code Issues Projects Releases Packages Wiki Activity
dioxus/docs/posts/08-custom-renderer.md
Jonathan Kelley a61503f6cc Feat: homepage update from rocket
2021-02-09 12:33:54 -05:00

2.2 KiB
Raw Blame History

Custom Renderer

Dioxus is an incredibly portable framework for UI development. The lessons, knowledge, hooks, and components you acquire over time can always be used for future projects. However, sometimes those projects cannot leverage a supported renderer or you need to implement your own better renderer.

Great news: the design of the renderer is entirely up to you! We provide suggestions and inspiration with the 1st party renderers, but provide no trait or explicit interface to follow.

Implementing the renderer is fairly straightforward. The renderer needs to:

  1. Handle the stream of edit events generated by updates to the virtual DOM
  2. Register listeners and pass events into the virtual DOM's event system
  3. Progress the virtual DOM with an async executor (or disable the suspense API and use progress_sync)

Essentially, your renderer needs to understand the EditEvent type and provide a callback for injecting events. From there, you'll have everything needed to render the VirtualDOM to the screen.

Internally, Dioxus handles the tree relationship, diffing, memory management, and the event system, leaving as little as possible required for renderers to implement themselves.

For inspiration, check out the source code for the various renderers we support:

  • WebSys
  • Morph

Compatibility

Forewarning: not every hook and service will work on your platform. Dioxus wraps things that need to be cross-platform in "synthetic" types. However, downcasting to a native type might fail if the types don't match.

There are three opportunities for platform incompatibilities to break your program:

  1. When downcasting elements via Ref.to_native<T>()
  2. When downcasting events via Event.to_native<T>()
  3. Calling platform-specific APIs that don't exist

The best hooks will properly detect the target platform and still provide functionality, failing gracefully when a platform is not supported. We encourage - and provide - an indication to the user on what platforms a hook supports. For issues 1 and 2, these return a result as to not cause panics on unsupported platforms. When designing your hooks, we recommend propagating this error upwards into user facing code, making it obvious that this particular service is not supported.