Components
Overview¶
We supply some pre-designed that components can be used to help simplify development.
PyScript Component¶
This allows you to embedded any number of client-side PyScript components within traditional ReactPy components.
By default, the only available dependencies are the Python standard library, pyscript
, pyodide
, reactpy
core.
The entire file path provided is loaded directly into the browser, and must have a def root()
component to act as the entry point.
Pitfall
Similar to JavaScript, your provided Python file is loaded directly into the client (web browser) as raw text to run using the PyScript interpreter. Be cautious about what you include in your Python file.
As a result being client-sided, Python packages within your local environment (such as those installed via pip install ...
) are not accessible within PyScript components.
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
See Interface
Parameters
Name | Type | Description | Default |
---|---|---|---|
*file_paths | str | File path to your client-side component. If multiple paths are provided, the contents are automatically merged. | N/A |
initial | str | VdomDict | ComponentType | The initial HTML that is displayed prior to the PyScript component loads. This can either be a string containing raw HTML, a reactpy.html snippet, or a non-interactive component. | "" |
root | str | The name of the root component function. | "root" |
You must call pyscript_setup
in your Django template before using this tag!
This requires using of the {% pyscript_setup %}
template tag to initialize PyScript on the client.
1 2 3 4 5 6 |
|
How do I execute JavaScript within PyScript components?
PyScript components several options available to execute JavaScript, including...
Pyodide JS Module
The Pyodide js
module has access to everything within the browser's JavaScript environment. Therefore, any global JavaScript functions loaded within your HTML <head>
can be called as well. However, you will need to be mindful of JavaScript load order if using async
or deferred
loading!
1 2 3 4 5 6 7 8 9 10 11 |
|
PyScript FFI
...
PyScript JS Modules
Assuming you have a local bundle stored within your project's static files, you can import JavaScript modules in a fashion similar to import {moment} from 'static/moment.js'
. You will first need to configure your {% pyscript_setup %}
block to make the moment.js
module available to PyScript. Then, this module can be accessed within pyscript.js_modules.*
.
1 2 3 4 5 6 7 8 9 10 11 12 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Does my entire component need to be contained in one file?
Splitting a large file into multiple files is a common practice in software development.
However, PyScript components are run on the client browser. As such, they do not have access to your local development environment, and thus cannot import
any local Python files.
If your PyScript component file gets too large, you can declare multiple file paths instead. These files will automatically combined by ReactPy.
Here is how we recommend splitting your component into multiple files while avoiding local imports but retaining type hints.
1 2 3 4 5 6 7 8 9 10 11 12 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 |
|
How do I display something while the component is loading?
You can configure the initial
keyword to display HTML while your PyScript component is loading.
The value for initial
is most commonly be a reactpy.html
snippet or a non-interactive @component
.
1 2 3 4 5 6 7 8 9 10 11 12 |
|
However, you can also use a string containing raw HTML.
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Can I use a different name for my root component?
Yes, you can use the root
keyword to specify a different name for your root function.
1 2 3 4 5 6 7 8 9 10 11 12 |
|
1 2 3 4 5 6 |
|
View To Component¶
Automatically convert a Django view into a component.
At this time, this works best with static views with no interactivity.
Compatible with sync or async Function Based Views and Class Based Views.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 |
|
See Interface
Parameters
Name | Type | Description | Default |
---|---|---|---|
view | Callable | View | str | The view to convert, or the view's dotted path as a string. | N/A |
transforms | Sequence[Callable[[VdomDict], Any]] | A list of functions that transforms the newly generated VDOM. The functions will be called on each VDOM node. | tuple |
strict_parsing | bool | If True , an exception will be generated if the HTML does not perfectly adhere to HTML5. | True |
Returns
Type | Description |
---|---|
constructor | A function that takes request, *args, key, **kwargs and returns a ReactPy component. Note that *args and **kwargs are directly provided to your view. |
Existing limitations
There are currently several limitations of using view_to_component
that may be resolved in a future version.
- Requires manual intervention to change HTTP methods to anything other than
GET
. - ReactPy events cannot conveniently be attached to converted view HTML.
- Has no option to automatically intercept local anchor link (such as
<a href='example/'></a>
) click events.
How do I use this for Class Based Views?
Class Based Views are accepted by view_to_component
as an argument.
Calling as_view()
is optional, but recommended.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 |
|
How do I provide request
, args
, and kwargs
to a converted view?
This component accepts request
, *args
, and **kwargs
arguments, which are sent to your provided view.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
1 2 3 4 5 |
|
How do I customize this component's behavior?
This component accepts arguments that can be used to customize its behavior.
Below are all the arguments that can be used.
strict_parsing
By default, an exception will be generated if your view's HTML does not perfectly adhere to HTML5.
However, there are some circumstances where you may not have control over the original HTML, so you may be unable to fix it. Or you may be relying on non-standard HTML tags such as <my-tag> Hello World </my-tag>
.
In these scenarios, you may want to rely on best-fit parsing by setting the strict_parsing
parameter to False
. This uses libxml2
recovery algorithm, which is designed to be similar to how web browsers would attempt to parse non-standard or broken HTML.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 |
|
transforms
After your view has been turned into VDOM (python dictionaries), view_to_component
will call your transforms
functions on every VDOM node.
This allows you to modify your view prior to rendering.
For example, if you are trying to modify the text of a node with a certain id
, you can create a transform like such:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
1 2 3 4 5 |
|
View To Iframe¶
Automatically convert a Django view into an iframe
element.
The contents of this iframe
is handled entirely by traditional Django view rendering. While this solution is compatible with more views than view_to_component
, it comes with different limitations.
Compatible with sync or async Function Based Views and Class Based Views.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
See Interface
Parameters
Name | Type | Description | Default |
---|---|---|---|
view | Callable | View | str | The view function or class to convert. | N/A |
extra_props | Mapping[str, Any] | None | Additional properties to add to the iframe element. | None |
Returns
Type | Description |
---|---|
constructor | A function that takes *args, key, **kwargs and returns a ReactPy component. Note that *args and **kwargs are directly provided to your view. |
Existing limitations
There are currently several limitations of using view_to_iframe
that may be resolved in a future version.
- No built-in method of signalling events back to the parent component.
- All provided
*args
and*kwargs
must be serializable values, since they are encoded into the URL. - The
iframe
will always load after the parent component. - CSS styling for
iframe
elements tends to be awkward/difficult.
How do I use this for Class Based Views?
Class Based Views are accepted by view_to_iframe
as an argument.
Calling as_view()
is optional, but recommended.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
How do I provide args
and kwargs
to a converted view?
This component accepts *args
and **kwargs
arguments, which are sent to your provided view.
All provided *args
and *kwargs
must be serializable values, since they are encoded into the URL.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
1 2 3 4 5 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
How do I customize this component's behavior?
This component accepts arguments that can be used to customize its behavior.
Below are all the arguments that can be used.
extra_props
This component accepts a extra_props
parameter, which is a dictionary of additional properties to add to the iframe
element.
For example, if you want to add a title
attribute to the iframe
element, you can do so like such:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Django CSS¶
Allows you to defer loading a CSS stylesheet until a component begins rendering. This stylesheet must be stored within Django's static files.
1 2 3 4 5 6 7 8 9 10 |
|
See Interface
Parameters
Name | Type | Description | Default |
---|---|---|---|
static_path | str | The path to the static file. This path is identical to what you would use on Django's {% static %} template tag. | N/A |
key | Key | None | A key to uniquely identify this component which is unique amongst a component's immediate siblings | None |
Returns
Type | Description |
---|---|
Component | A ReactPy component. |
Can I load static CSS using html.link
instead?
While you can load stylesheets with html.link
, keep in mind that loading this way does not ensure load order. Thus, your stylesheet will be loaded after your component is displayed. This would likely cause unintended visual behavior, so use this at your own discretion.
Here's an example on what you should avoid doing for Django static files:
1 2 3 4 5 6 7 8 9 10 |
|
How do I load external CSS?
django_css
can only be used with local static files.
For external CSS, you should use html.link
.
1 2 3 4 5 6 7 8 9 10 11 |
|
Why not load my CSS in <head>
?
Traditionally, stylesheets are loaded in your <head>
using Django's {% static %}
template tag.
However, to help improve webpage load times you can use this django_css
component to defer loading your stylesheet until it is needed.
Django JS¶
Allows you to defer loading JavaScript until a component begins rendering. This JavaScript must be stored within Django's static files.
1 2 3 4 5 6 7 8 9 10 |
|
See Interface
Parameters
Name | Type | Description | Default |
---|---|---|---|
static_path | str | The path to the static file. This path is identical to what you would use on Django's {% static %} template tag. | N/A |
key | Key | None | A key to uniquely identify this component which is unique amongst a component's immediate siblings | None |
Returns
Type | Description |
---|---|
Component | A ReactPy component. |
Can I load static JavaScript using html.script
instead?
While you can load JavaScript with html.script
, keep in mind that loading this way does not ensure load order. Thus, your JavaScript will likely be loaded at an arbitrary time after your component is displayed.
Here's an example on what you should avoid doing for Django static files:
1 2 3 4 5 6 7 8 9 10 |
|
How do I load external JS?
django_js
can only be used with local static files.
For external JavaScript, you should use html.script
.
1 2 3 4 5 6 7 8 9 |
|
Why not load my JS in <head>
?
Traditionally, JavaScript is loaded in your <head>
using Django's {% static %}
template tag.
However, to help improve webpage load times you can use this django_js
component to defer loading your JavaScript until it is needed.