Skip to content

Commit c86c59d

Browse files
rmorshearmorshea
authored
doc improvements (#984)
* fix js template links * better HTML docs
1 parent 07f5521 commit c86c59d

File tree

5 files changed

+220
-15
lines changed

5 files changed

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

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

0 commit comments

Comments
 (0)