@@ -3,19 +3,23 @@ Django React
33
44[ ![ Build Status] ( https://travis-ci.org/markfinger/django-react.svg?branch=master )] ( https://travis-ci.org/markfinger/django-react )
55
6- Render React components from a Django application.
6+ Render and bundle React components from a Django application.
77
88``` python
99from django_react.render import render_component
1010
11- props = {
12- ' foo' ' bar'
11+ # Render a JSX component
12+ component = render_component(' path/to/component.jsx' translate = True , props = {
13+ ' foo' ' bar'
1314 ' woz' 1 ,2 ,3 ],
14- }
15+ })
1516
16- rendered = render_component(' path/to/component.jsx' props = props)
17+ # The rendered markup
18+ print (component)
1719
18- print (rendered)
20+ # Render JavaScript that will reuse the data provided and mount the component
21+ # on the client-side
22+ print (component.render_js())
1923```
2024
2125Documentation
@@ -88,37 +92,77 @@ Arguments:
8892- ` to_static_markup ` * optional* — a boolean indicating that React's ` renderToStaticMarkup `
8993 method should be used for the rendering. Defaults to ` False ` , which causes React's
9094 ` renderToString ` method to be used.
95+ - ` bundle ` * optional* - a boolean indicating that the component should be bundled for
96+ reuse on the client-side. If ` translate ` or ` watch_source ` are used, this argument is
97+ ignored.
98+ - ` translate ` * optional* - a boolean indicating that the component should be translated
99+ from JSX and ES6/7 before rendering.
91100- ` watch_source ` * optional* — a boolean indicating that the renderer should watch your source
92- files and rebuild the component everytime it changes. Defaults to ` True ` , in development .
93- - ` json_encoder ` * optional* — a class which is used to encode the JSON which is sent to the
94- renderer. Defaults to ` django.core.serializers.json.DjangoJSONEncoder ` .
101+ files and rebuild the component whenever it changes. If not defined, defaults to ` DEBUG ` .
102+ - ` json_encoder ` * optional* — a class which is used to encode the props to JSON. Defaults
103+ to ` django.core.serializers.json.DjangoJSONEncoder ` .
95104
96105
97106RenderedComponent
98107-----------------
99108
100- The result of rendering a component to its initial HTML . RenderedComponents can be passed
101- directly into templates where they output the generated HTML .
109+ The result of rendering a component to its initial markup . RenderedComponents can be passed
110+ directly into templates where they will output the generated markup .
102111
103112``` python
104113# Render the component
105- my_component = render_component(... )
114+ component = render_component(... )
106115
107- # Print the generated HTML
108- print (my_component )
116+ # Print the generated markup
117+ print (component )
109118```
110119``` html
111120<!-- Insert the generated HTML into your template -->
112- {{ my_component }}
121+ {{ component }}
113122```
114123
115- RenderedComponents have a helper method, ` render_props ` , which outputs your JSON-serialized
116- props. This allows you to reuse the encoded form of your props on the client-side .
124+ Components can be remounted on the client-side, so that the same codebase and data
125+ can be reused to provide interactivity .
117126
118127``` html
119- <script >
120- var myProps = {{ my_component .render_props }};
121- script >
128+ <script src =" path/to/react.js" script >
129+
130+ {{ component.render_js }}
131+ ```
132+
133+ * Note* : if you wish to use the ` render_js ` method, you * must* provide a ` <script> ` element
134+ pointing to React. React is omitted from the bundled component so that build times are reduced,
135+ and to ensure that multiple components can be included on a single page without duplicating
136+ React's codebase.
137+
138+ Be aware that the mounting strategy used by ` render_js ` is fairly basic, if you want to use
139+ a more custom solution there are a couple of helpers provided to assist:
140+ ``` python
141+ The data used to render the component, this can be plugged straight into the client- side
142+ print (component.render_props())
143+
144+ # The bundled component (a WebpackBundle instance)
145+ component.get_bundle()
146+
147+ # Render a script element pointing to the bundled component
148+ print (component.get_bundle().render())
149+
150+ # The variable that the bundle exposes the component as on the global scope
151+ print (component.get_var())
152+
153+ # Returns an absolute path to the location of the component's bundle on the file-system
154+ print (component.bundle.get_path())
155+
156+ # When rendering a bundled component, the component is wrapped in a container
157+ # element to allow the mount JS to target it. You can use this selector to
158+ # target the container element
159+ print (component.get_container_id())
160+
161+ # The rendered markup without the container element wrapping it
162+ print (component.markup)
163+
164+ # Render the JS used to mount the bundled component over the rendered component
165+ print (component.render_mount_js())
122166```
123167
124168
0 commit comments