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

Diff for: ‎docs/source/_custom_js/package-lock.json

+1-3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

+14-5
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

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

+7-7
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

Diff for: ‎docs/source/index.rst

+1
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

Diff for: ‎docs/source/reference/html-attributes.rst

+192
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)