Crate dioxus_elements

Expand description

§`dioxus-html`: Html (and SVG) Namespace for Dioxus

§Overview

The Dioxus rsx! macro can accept any compile-time correct namespace on top of NodeFactory. This crate provides the HTML (and SVG) namespaces which get imported in the Dioxus prelude.

However, this abstraction enables you to add any namespace of elements, provided they’re in scope when rsx! is called. For an example, a UI that is designed for Augmented Reality might use different primitives than HTML:

use ar_namespace::*;

rsx! {
    magic_div {
        magic_header {}
        magic_paragraph {
            on_magic_click: move |event| {
                //
            }
        }
    }
}

This is currently a not-very-explored part of Dioxus. However, the namespacing system does make it possible to provide syntax highlighting, documentation, “go to definition” and compile-time correctness, so it’s worth having it abstracted.

§How it works:

Elements for dioxus must implement the (simple) DioxusElement trait to be used in the rsx! macro.

struct div;
impl DioxusElement for div {
    const TAG_NAME: &'static str = "div";
    const NAME_SPACE: Option<&'static str> = None;
}

All elements should be defined as a zero-sized-struct (also known as unit struct). These structs are zero-cost and just provide the type-level trickery to Rust for compile-time correct templates.

Attributes would then be implemented as constants on these unit structs.

The HTML namespace is defined mostly with macros. However, the expanded form would look something like this:

struct base;
impl DioxusElement for base {
    const TAG_NAME: &'static str = "base";
    const NAME_SPACE: Option<&'static str> = None;
}
impl base {
    const href: (&'static str, Option<'static str>, bool) = ("href", None, false);
    const target: (&'static str, Option<'static str>, bool) = ("target", None, false);
}

Because attributes are defined as methods on the unit struct, they guard the attribute creation behind a compile-time correct interface.

§How to extend it:

Whenever the rsx! macro is called, it relies on a module dioxus_elements to be in scope. When you enable the html feature in dioxus, this module gets imported in the prelude. However, you can extend this with your own set of custom elements by making your own dioxus_elements module and re-exporting the html namespace.

mod dioxus_elements {
    use dioxus::prelude::dioxus_elements::*;
    struct my_element;
    impl DioxusElement for my_element {
        const TAG_NAME: &'static str = "base";
        const NAME_SPACE: Option<&'static str> = None;
    }
}

§Contributing

Report issues on our issue tracker.
Join the discord and ask questions!

§License

This project is licensed under the MIT license.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions.

§Dioxus Namespace for HTML

This crate provides a set of compile-time correct HTML elements that can be used with the Rsx and Html macros. This system allows users to easily build new tags, new types, and customize the output of the Rsx and Html macros.

An added benefit of this approach is the ability to lend comprehensive documentation on how to use these elements inside of the Rsx and Html macros. Each element comes with a substantial amount of documentation on how to best use it, hopefully making the development cycle quick.

All elements are used as zero-sized unit structs with trait impls.

Currently, we don’t validate for structures, but do validate attributes.

Modules§

elements
events: Event Handlers
extensions
geometry: Geometry primitives for representing e.g. mouse events
global_attributes
input_data: Data structures representing user input, such as modifier keys and mouse buttons
point_interaction
prelude
svg_attributes

Structs§

AnimationData
ClipboardData
CompositionData
DragData: The DragEvent interface is a DOM event that represents a drag and drop interaction. The user initiates a drag by placing a pointer device (such as a mouse) on the touch surface and then dragging the pointer to a new location (such as another DOM element). Applications are free to interpret a drag and drop interaction in an application-specific way.
FocusData
FormData
FormValue: A form value that may either be a list of values or a single value
ImageData
KeyboardData
MediaData
MountedData: An Element that has been rendered and allows reading and modifying information about it.
MouseData: A synthetic event that wraps a web-style MouseEvent Data associated with a mouse event
PlatformEventData: A platform specific event.
PointerData
ResizeData
ScrollData
SelectionData
ToggleData
TouchData
TouchPoint
TransitionData
VisibleData
WheelData: Data associated with a WheelEvent

Enums§

KeyCode
MountedError: The error type for the MountedData
ResizeError: The error type for the MountedData
ScrollBehavior: The way that scrolling should be performed
VisibleError: The error type for the VisibleData

Traits§

FileEngine
GlobalAttributesExtension
HasAnimationData: A trait for any object that has the data for an animation event
HasClipboardData
HasCompositionData: A trait for any object that has the data for a composition event
HasDragData: A trait for any object that has the data for a drag event
HasFileData
HasFocusData
HasFormData: An object that has all the data for a form event
HasImageData: A trait for any object that has the data for an image event
HasKeyboardData
HasMediaData
HasMouseData: A trait for any object that has the data for a mouse event
HasPointerData: A trait for any object that has the data for a pointer event
HasResizeData
HasScrollData
HasSelectionData
HasToggleData
HasTouchData
HasTouchPointData: A trait for touch point data
HasTransitionData
HasVisibleData
HasWheelData
HtmlEventConverter: A converter between a platform specific event and a general event. All code in a renderer that has a large binary size should be placed in this trait. Each of these functions should be snipped in high levels of optimization.
RenderedElementBacking: An Element that has been rendered and allows reading and modifying information about it.
SvgAttributesExtension

Functions§

onabort: abort
onanimationend: onanimationend
onanimationiteration: onanimationiteration
onanimationstart: onanimationstart
onblur: onblur
oncanplay: canplay
oncanplaythrough: canplaythrough
onchange: onchange
onclick: Execute a callback when a button is clicked.
oncompositionend: oncompositionend
oncompositionstart: oncompositionstart
oncompositionupdate: oncompositionupdate
oncontextmenu: oncontextmenu
oncopy: oncopy
oncut: oncut
ondblclickDeprecated: General Event Handler Information
ondoubleclick: General Event Handler Information
ondrag: ondrag
ondragend: ondragend
ondragenter: ondragenter
ondragexit: ondragexit
ondragleave: ondragleave
ondragover: ondragover
ondragstart: ondragstart
ondrop: ondrop
ondurationchange: durationchange
onemptied: emptied
onencrypted: encrypted
onended: ended
onerror: onerror
onfocus: onfocus
onfocusin: General Event Handler Information
onfocusout: General Event Handler Information
ongotpointercapture: gotpointercapture
oninput: The oninput event is fired when the value of a <input>, <select>, or <textarea> element is changed.
oninvalid: oninvalid
onkeydown: onkeydown
onkeypress: onkeypress
onkeyup: onkeyup
onload: onload
onloadeddata: loadeddata
onloadedmetadata: loadedmetadata
onloadstart: loadstart
onlostpointercapture: lostpointercapture
onmounted: The onmounted event is fired when the element is first added to the DOM. This event gives you a MountedData object and lets you interact with the raw DOM element.
onmousedown: onmousedown
onmouseenter: onmouseenter
onmouseleave: onmouseleave
onmousemove: onmousemove
onmouseout: onmouseout
onmouseover: onmouseover
onmouseup: onmouseup
onpaste: onpaste
onpause: pause
onplay: play
onplaying: playing
onpointercancel: pointercancel
onpointerdown: pointerdown
onpointerenter: pointerenter
onpointerleave: pointerleave
onpointermove: pointermove
onpointerout: pointerout
onpointerover: pointerover
onpointerup: pointerup
onprogress: progress
onratechange: ratechange
onreset: onreset
onresize: onresize
onscroll: onscroll
onseeked: seeked
onseeking: seeking
onselect: select
onselectionchange: selectionchange
onselectstart: selectstart
onstalled: stalled
onsubmit: onsubmit
onsuspend: suspend
ontimeupdate: timeupdate
ontoggle: ontoggle
ontouchcancel: touchcancel
ontouchend: touchend
ontouchmove: touchmove
ontouchstart: touchstart
ontransitionend: transitionend
onvisible: onvisible
onvolumechange: volumechange
onwaiting: waiting
onwheel: Called when the mouse wheel is rotated over an element.
render_template_to_html: Render a template to an HTML string
set_event_converter

Type Aliases§

AnimationEvent
AttributeDescription
ClipboardEvent
CompositionEvent
DragEvent
FocusEvent
FormEvent
ImageEvent
KeyboardEvent
MediaEvent
MountedEvent
MountedResult: The MountedResult type for the MountedData
MouseEvent
PointerEvent: A synthetic event that wraps a web-style PointerEvent
ResizeEvent
ResizeResult: The ResizeResult type for the ResizeData
ScrollEvent
SelectionEvent
ToggleEvent
TouchEvent
TransitionEvent
VisibleEvent
VisibleResult: The VisibleResult type for the VisibleData
WheelEvent: A synthetic event that wraps a web-style WheelEvent