Skip to content

Commit e5da299

Browse files
rmorshearmorshea
committed
better HTML docs
1 parent 07f5521 commit e5da299

File tree

5 files changed

+215
-15
lines changed

5 files changed

+215
-15
lines changed

‎docs/source/_custom_js/package-lock.json

Lines changed: 1 addition & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/source/guides/creating-interfaces/html-with-reactpy/index.rst

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -78,22 +78,20 @@ to specify a URL to its ``src`` and use some ``style`` to modify and position it
7878

7979
<img
8080
src="https://picsum.photos/id/237/500/300"
81+
class="img-fluid"
8182
style="width: 50%; margin-left: 25%;"
8283
alt="Billie Holiday"
8384
tabindex="0"
8485
/>
8586

86-
In ReactPy we add these attributes to elements using keyword arguments. There are two main
87-
notable differences though. First, all names in ReactPy use ``snake_case`` instead of
88-
dash-separated words. For example, ``tabindex`` and ``margin-left`` become ``tab_index``
89-
and ``margin_left`` respectively. Second, instead of specifying ``style`` using a
90-
string, we use a dictionary. Given this, you can rewrite the ``<img>`` element above as:
87+
In ReactPy we add these attributes to elements using a dictionary:
9188

9289
.. testcode::
9390

9491
html.img(
9592
{
9693
"src": "https://picsum.photos/id/237/500/300",
94+
"class_name": "img-fluid",
9795
"style": {"width": "50%", "margin_left": "25%"},
9896
"alt": "Billie Holiday",
9997
}
@@ -104,10 +102,21 @@ string, we use a dictionary. Given this, you can rewrite the ``<img>`` element a
104102
<!-- no tabindex since that would ruin accesibility of the page -->
105103
<img
106104
src="https://picsum.photos/id/237/500/300"
105+
class="img-fluid"
107106
style="width: 50%; margin-left: 25%;"
108107
alt="Billie Holiday"
109108
/>
110109

110+
There are some notable differences. First, all names in ReactPy use ``snake_case`` instead
111+
of dash-separated words. For example, ``tabindex`` and ``margin-left`` become
112+
``tab_index`` and ``margin_left`` respectively. Second, instead of using a string to
113+
specify the ``style`` attribute, we use a dictionary to describe the CSS properties we
114+
want to apply to an element. This is done to avoid having to escape quotes and other
115+
characters in the string. Finally, the ``class`` attribute is renamed to ``class_name``
116+
to avoid conflicting with the ``class`` keyword in Python.
117+
118+
For full list of supported attributes and differences from HTML, see the
119+
:ref:`HTML Attributes` reference.
111120

112121
----------
113122

‎docs/source/guides/creating-interfaces/rendering-data/index.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -80,10 +80,6 @@ With this we can now imaging writing some filtering and sorting logic using Pyth
8080
displaying items whose ``priority`` is less than or equal to some ``filter_by_priority``
8181
and then ordering the elements based on the ``priority``:
8282

83-
.. testcode::
84-
85-
x = 1
86-
8783
.. testcode::
8884

8985
filter_by_priority = 1
@@ -105,6 +101,11 @@ and then ordering the elements based on the ``priority``:
105101

106102
We could then add this code to our ``DataList`` component:
107103

104+
.. warning::
105+
106+
The code below produces a bunch of warnings! Be sure to tead the
107+
:ref:`next section <Organizing Items With Keys>` to find out why.
108+
108109
.. reactpy:: _examples/sorted_and_filtered_todo_list
109110

110111

@@ -135,12 +136,11 @@ structure even further to include a unique ID for each item in our todo list:
135136
{"id": 7, "text": "Read a book", "priority": 1},
136137
]
137138

138-
Then, as we're constructing our ``<li>`` elements we'll pass in a ``key`` argument to
139-
the element constructor:
139+
Then, as we're constructing our ``<li>`` elements we'll declare a ``key`` attribute:
140140

141141
.. code-block::
142142
143-
list_item_elements = [html.li(t["text"], key=t["id"]) for t in tasks]
143+
list_item_elements = [html.li({"key": t["id"]}, t["text"]) for t in tasks]
144144
145145
This ``key`` tells ReactPy which ``<li>`` element corresponds to which item of data in our
146146
``tasks`` list. This becomes important if the order or number of items in your list can

‎docs/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ ReactPy
2323
:caption: Reference
2424

2525
reference/browser-events
26+
reference/html-attributes
2627
reference/hooks-api
2728
_auto/apis
2829
reference/javascript-api

‎docs/source/reference/html-attributes.rst

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
HTML Attributes
2+
===============
3+
4+
In ReactPy, HTML attributes are specified using snake_case instead of dash-separated
5+
words. For example, ``tabindex`` and ``margin-left`` become ``tab_index`` and
6+
``margin_left`` respectively.
7+
8+
9+
Noteable Attributes
10+
-------------------
11+
12+
Some attributes in ReactPy are renamed, have special meaning, or are used differently
13+
than in HTML.
14+
15+
``style``
16+
.........
17+
18+
As mentioned above, instead of using a string to specify the ``style`` attribute, we use
19+
a dictionary to describe the CSS properties we want to apply to an element. For example,
20+
the following HTML:
21+
22+
.. code-block:: html
23+
24+
<div style="width: 50%; margin-left: 25%;">
25+
<h1 style="margin-top: 0px;">My Todo List</h1>
26+
<ul>
27+
<li>Build a cool new app</li>
28+
<li>Share it with the world!</li>
29+
</ul>
30+
</div>
31+
32+
Would be written in ReactPy as:
33+
34+
.. testcode::
35+
36+
html.div(
37+
{
38+
"style": {
39+
"width": "50%",
40+
"margin_left": "25%",
41+
},
42+
},
43+
html.h1(
44+
{
45+
"style": {
46+
"margin_top": "0px",
47+
},
48+
},
49+
"My Todo List",
50+
),
51+
html.ul(
52+
html.li("Build a cool new app"),
53+
html.li("Share it with the world!"),
54+
),
55+
)
56+
57+
``class`` vs ``class_name``
58+
...........................
59+
60+
In HTML, the ``class`` attribute is used to specify a CSS class for an element. In
61+
ReactPy, this attribute is renamed to ``class_name`` to avoid conflicting with the
62+
``class`` keyword in Python. For example, the following HTML:
63+
64+
.. code-block:: html
65+
66+
<div class="container">
67+
<h1 class="title">My Todo List</h1>
68+
<ul class="list">
69+
<li class="item">Build a cool new app</li>
70+
<li class="item">Share it with the world!</li>
71+
</ul>
72+
</div>
73+
74+
Would be written in ReactPy as:
75+
76+
.. testcode::
77+
78+
html.div(
79+
{"class_name": "container"},
80+
html.h1({"class_name": "title"}, "My Todo List"),
81+
html.ul(
82+
{"class_name": "list"},
83+
html.li({"class_name": "item"}, "Build a cool new app"),
84+
html.li({"class_name": "item"}, "Share it with the world!"),
85+
),
86+
)
87+
88+
``for`` vs ``html_for``
89+
.......................
90+
91+
In HTML, the ``for`` attribute is used to specify the ``id`` of the element it's
92+
associated with. In ReactPy, this attribute is renamed to ``html_for`` to avoid
93+
conflicting with the ``for`` keyword in Python. For example, the following HTML:
94+
95+
.. code-block:: html
96+
97+
<div>
98+
<label for="todo">Todo:</label>
99+
<input id="todo" type="text" />
100+
</div>
101+
102+
Would be written in ReactPy as:
103+
104+
.. testcode::
105+
106+
html.div(
107+
html.label({"html_for": "todo"}, "Todo:"),
108+
html.input({"id": "todo", "type": "text"}),
109+
)
110+
111+
``dangerously_set_inner_HTML``
112+
..............................
113+
114+
This is used to set the ``innerHTML`` property of an element and should be provided a
115+
dictionary with a single key ``__html`` whose value is the HTML to be set. It should be
116+
used with **extreme caution** as it can lead to XSS attacks if the HTML inside isn't
117+
trusted (for example if it comes from user input).
118+
119+
120+
All Attributes
121+
--------------
122+
123+
`access_key <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey>`__
124+
A string. Specifies a keyboard shortcut for the element. Not generally recommended.
125+
126+
`aria_* <https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes>`__
127+
ARIA attributes let you specify the accessibility tree information for this element.
128+
See ARIA attributes for a complete reference. In ReactPr, all ARIA attribute names are
129+
exactly the same as in HTML.
130+
131+
`auto_capitalize <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autocapitalize>`__
132+
A string. Specifies whether and how the user input should be capitalized.
133+
134+
`content_editable <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contenteditable>`__
135+
A boolean. If true, the browser lets the user edit the rendered element directly. This
136+
is used to implement rich text input libraries like Lexical. ReactPr warns if you try
137+
to pass children to an element with ``content_editable = True`` because ReactPy will
138+
not be able to update its content after user edits.
139+
140+
`data_* <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*>`__
141+
Data attributes let you attach some string data to the element, for example
142+
data-fruit="banana". In ReactPy, they are not commonly used because you would usually
143+
read data from props or state instead.
144+
145+
`dir <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir>`__
146+
Either ``"ltr"`` or ``"rtl"``. Specifies the text direction of the element.
147+
148+
`draggable <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable>`__
149+
A boolean. Specifies whether the element is draggable. Part of HTML Drag and Drop API.
150+
151+
`enter_key_hint <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint>`__
152+
A string. Specifies which action to present for the enter key on virtual keyboards.
153+
154+
`hidden <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden>`__
155+
A boolean or a string. Specifies whether the element should be hidden.
156+
157+
- `id <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id>`__:
158+
A string. Specifies a unique identifier for this element, which can be used to find it
159+
later or connect it with other elements. Generate it with useId to avoid clashes
160+
between multiple instances of the same component.
161+
162+
`is <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-is>`__
163+
A string. If specified, the component will behave like a custom element.
164+
165+
`input_mode <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode>`__
166+
A string. Specifies what kind of keyboard to display (for example, text, number, or telephone).
167+
168+
`item_prop <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop>`__
169+
A string. Specifies which property the element represents for structured data crawlers.
170+
171+
`lang <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang>`__
172+
A string. Specifies the language of the element.
173+
174+
`role <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/role>`__
175+
A string. Specifies the element role explicitly for assistive technologies.
176+
177+
`slot <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot>`__
178+
A string. Specifies the slot name when using shadow DOM. In ReactPy, an equivalent
179+
pattern is typically achieved by passing JSX as props, for example
180+
``<Layout left={<Sidebar />} right={<Content />} />``.
181+
182+
`spell_check <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck>`__
183+
A boolean or null. If explicitly set to true or false, enables or disables spellchecking.
184+
185+
`tab_index <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex>`__
186+
A number. Overrides the default Tab button behavior. Avoid using values other than -1 and 0.
187+
188+
`title <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title>`__
189+
A string. Specifies the tooltip text for the element.
190+
191+
`translate <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/translate>`__
192+
Either 'yes' or 'no'. Passing 'no' excludes the element content from being translated.

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy