Skip to content

Commit 3eb8481

Browse files
bckohanbckohan
committed
change order of examples on readme
1 parent e5dd0e0 commit 3eb8481

File tree

1 file changed

+141
-141
lines changed

1 file changed

+141
-141
lines changed

‎README.md‎

Lines changed: 141 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -83,86 +83,113 @@ $> manage.py collectstatic
8383

8484
## Usage
8585

86-
### Transpiling Model Field Choices
86+
### Transpiling URL reversal
8787

88-
You have an app with a model with a character field that has several valid choices defined in an
89-
enumeration type way, and you'd like to export those defines to JavaScript. You'd like to include
90-
a template for other's using your app to use to generate a defines.js file. Say your app structure
91-
looks like this::
88+
You'd like to be able to call something like `reverse` on path names from your client JavaScript
89+
code the same way you do from Python Django code.
9290

93-
.
94-
└── examples
95-
├── __init__.py
96-
├── apps.py
97-
├── defines.py
98-
├── models.py
99-
├── static_templates
100-
│   └── examples
101-
│   └── defines.js
102-
└── urls.py
91+
Your settings file might look like:
10392

93+
```python
94+
STATIC_TEMPLATES={
95+
'ENGINES': [{
96+
'BACKEND': 'render_static.backends.StaticDjangoTemplates',
97+
'OPTIONS': {
98+
'loaders': [
99+
('render_static.loaders.StaticLocMemLoader', {
100+
'urls.js': '{% urls_to_js %}'
101+
})
102+
]
103+
},
104+
}],
105+
'templates': ['urls.js']
106+
}
107+
```
104108

105-
Your defines/model classes might look like this:
109+
Then call `renderstatic` before `collectstatic`:
110+
111+
```shell
112+
$> ./manage.py renderstatic
113+
$> ./manage.py collectstatic
114+
```
115+
116+
If your root urls.py looks like this:
106117

107118
```python
108-
class ExampleModel(Defines, models.Model):
119+
from django.contrib import admin
120+
from django.urls import path
109121

110-
DEFINE1 = 'D1'
111-
DEFINE2 = 'D2'
112-
DEFINE3 = 'D3'
113-
DEFINES = (
114-
(DEFINE1, 'Define 1'),
115-
(DEFINE2, 'Define 2'),
116-
(DEFINE3, 'Define 3')
117-
)
122+
from .views import MyView
118123

119-
define_field = models.CharField(choices=DEFINES, max_length=2)
124+
urlpatterns = [
125+
path('admin/', admin.site.urls),
126+
path('simple', MyView.as_view(), name='simple'),
127+
path('simple/<int:arg1>', MyView.as_view(), name='simple'),
128+
path('different/<int:arg1>/<str:arg2>', MyView.as_view(), name='different'),
129+
]
120130
```
121131

122-
And your defines.js template might look like this:
132+
So you can now fetch paths like this, in a way that is roughly API-equivalent
133+
to Django's `reverse` function:
123134

124-
```js+django
125-
{% defines_to_js modules="examples.models" %}
135+
```javascript
136+
import { URLResolver } from '/static/urls.js';
137+
138+
const urls = new URLResolver();
139+
140+
// /different/143/emma
141+
urls.reverse('different', {kwargs: {'arg1': 143, 'arg2': 'emma'}});
142+
143+
// reverse also supports query parameters
144+
// /different/143/emma?intarg=0&listarg=A&listarg=B&listarg=C
145+
urls.reverse(
146+
'different',
147+
{
148+
kwargs: {arg1: 143, arg2: 'emma'},
149+
query: {
150+
intarg: 0,
151+
listarg: ['A', 'B', 'C']
152+
}
153+
}
154+
);
126155
```
127156

128-
If someone wanted to use your defines template to generate a JavaScript version of your Python
129-
class their settings file might look like this:
157+
### URLGenerationFailed Exceptions & Placeholders
158+
159+
If you encounter a ``URLGenerationFailed`` exception you most likely need to register a placeholder for the argument in question. A placeholder is just a string or object that can be coerced to a string that matches the regular expression for the argument:
130160

131161
```python
132-
STATIC_TEMPLATES = {
133-
'templates': [
134-
'examples/defines.js'
135-
]
136-
}
162+
from render_static.placeholders import register_variable_placeholder
163+
164+
app_name = 'year_app'
165+
urlpatterns = [
166+
re_path(r'^fetch/(?P<year>\d{4})/$', YearView.as_view(), name='fetch_year')
167+
]
168+
169+
register_variable_placeholder('year', 2000, app_name=app_name)
137170
```
138171

172+
Users should typically use a path instead of re_path and register their own custom converters when needed. Placeholders can be directly registered on the converter (and are then conveniently available to users of your app!):
173+
174+
```python
175+
from django.urls.converters import register_converter
139176

140-
And then of course they would call `renderstatic` before `collectstatic`:
177+
class YearConverter:
178+
regex = '[0-9]{4}'
179+
placeholder = 2000 # this attribute is used by `url_to_js` to reverse paths
141180

142-
```shell
143-
$> ./manage.py renderstatic
144-
$> ./manage.py collectstatic
145-
```
181+
def to_python(self, value):
182+
return int(value)
146183

147-
This would create the following file::
184+
def to_url(self, value):
185+
return str(value)
148186

149-
.
150-
└── examples
151-
└── static
152-
└── examples
153-
└── defines.js
154187

155-
Which would look like this:
188+
register_converter(YearConverter, 'year')
156189

157-
```javascript
158-
const defines = {
159-
ExampleModel: {
160-
DEFINE1: "D1",
161-
DEFINE2: "D2",
162-
DEFINE3: "D3",
163-
DEFINES: [["D1", "Define 1"], ["D2", "Define 2"], ["D3", "Define 3"]]
164-
}
165-
};
190+
urlpatterns = [
191+
path('fetch/<year:year>', YearView.as_view(), name='fetch_year')
192+
]
166193
```
167194

168195
### Transpiling Enumerations
@@ -246,111 +273,84 @@ for (const color of Color) {
246273
}
247274
```
248275

249-
### Transpiling URL reversal
250-
251-
You'd like to be able to call something like `reverse` on path names from your client JavaScript
252-
code the same way you do from Python Django code.
253-
254-
Your settings file might look like:
276+
### Transpiling Model Field Choices
255277

256-
```python
257-
STATIC_TEMPLATES={
258-
'ENGINES': [{
259-
'BACKEND': 'render_static.backends.StaticDjangoTemplates',
260-
'OPTIONS': {
261-
'loaders': [
262-
('render_static.loaders.StaticLocMemLoader', {
263-
'urls.js': '{% urls_to_js %}'
264-
})
265-
]
266-
},
267-
}],
268-
'templates': ['urls.js']
269-
}
270-
```
278+
You have an app with a model with a character field that has several valid choices defined in an
279+
enumeration type way, and you'd like to export those defines to JavaScript. You'd like to include
280+
a template for other's using your app to use to generate a defines.js file. Say your app structure
281+
looks like this::
271282

272-
Then call `renderstatic` before `collectstatic`:
283+
.
284+
└── examples
285+
├── __init__.py
286+
├── apps.py
287+
├── defines.py
288+
├── models.py
289+
├── static_templates
290+
│   └── examples
291+
│   └── defines.js
292+
└── urls.py
273293

274-
```shell
275-
$> ./manage.py renderstatic
276-
$> ./manage.py collectstatic
277-
```
278294

279-
If your root urls.py looks like this:
295+
Your defines/model classes might look like this:
280296

281297
```python
282-
from django.contrib import admin
283-
from django.urls import path
298+
class ExampleModel(Defines, models.Model):
284299

285-
from .views import MyView
300+
DEFINE1 = 'D1'
301+
DEFINE2 = 'D2'
302+
DEFINE3 = 'D3'
303+
DEFINES = (
304+
(DEFINE1, 'Define 1'),
305+
(DEFINE2, 'Define 2'),
306+
(DEFINE3, 'Define 3')
307+
)
286308

287-
urlpatterns = [
288-
path('admin/', admin.site.urls),
289-
path('simple', MyView.as_view(), name='simple'),
290-
path('simple/<int:arg1>', MyView.as_view(), name='simple'),
291-
path('different/<int:arg1>/<str:arg2>', MyView.as_view(), name='different'),
292-
]
309+
define_field = models.CharField(choices=DEFINES, max_length=2)
293310
```
294311

295-
So you can now fetch paths like this, in a way that is roughly API-equivalent
296-
to Django's `reverse` function:
297-
298-
```javascript
299-
import { URLResolver } from '/static/urls.js';
300-
301-
const urls = new URLResolver();
302-
303-
// /different/143/emma
304-
urls.reverse('different', {kwargs: {'arg1': 143, 'arg2': 'emma'}});
312+
And your defines.js template might look like this:
305313

306-
// reverse also supports query parameters
307-
// /different/143/emma?intarg=0&listarg=A&listarg=B&listarg=C
308-
urls.reverse(
309-
'different',
310-
{
311-
kwargs: {arg1: 143, arg2: 'emma'},
312-
query: {
313-
intarg: 0,
314-
listarg: ['A', 'B', 'C']
315-
}
316-
}
317-
);
314+
```js+django
315+
{% defines_to_js modules="examples.models" %}
318316
```
319317

320-
### URLGenerationFailed Exceptions & Placeholders
321-
322-
If you encounter a ``URLGenerationFailed`` exception you most likely need to register a placeholder for the argument in question. A placeholder is just a string or object that can be coerced to a string that matches the regular expression for the argument:
318+
If someone wanted to use your defines template to generate a JavaScript version of your Python
319+
class their settings file might look like this:
323320

324321
```python
325-
from render_static.placeholders import register_variable_placeholder
326-
327-
app_name = 'year_app'
328-
urlpatterns = [
329-
re_path(r'^fetch/(?P<year>\d{4})/$', YearView.as_view(), name='fetch_year')
330-
]
331-
332-
register_variable_placeholder('year', 2000, app_name=app_name)
322+
STATIC_TEMPLATES = {
323+
'templates': [
324+
'examples/defines.js'
325+
]
326+
}
333327
```
334328

335-
Users should typically use a path instead of re_path and register their own custom converters when needed. Placeholders can be directly registered on the converter (and are then conveniently available to users of your app!):
336-
337-
```python
338-
from django.urls.converters import register_converter
339329

340-
class YearConverter:
341-
regex = '[0-9]{4}'
342-
placeholder = 2000 # this attribute is used by `url_to_js` to reverse paths
330+
And then of course they would call `renderstatic` before `collectstatic`:
343331

344-
def to_python(self, value):
345-
return int(value)
332+
```shell
333+
$> ./manage.py renderstatic
334+
$> ./manage.py collectstatic
335+
```
346336

347-
def to_url(self, value):
348-
return str(value)
337+
This would create the following file::
349338

339+
.
340+
└── examples
341+
└── static
342+
└── examples
343+
└── defines.js
350344

351-
register_converter(YearConverter, 'year')
345+
Which would look like this:
352346

353-
urlpatterns = [
354-
path('fetch/<year:year>', YearView.as_view(), name='fetch_year')
355-
]
347+
```javascript
348+
const defines = {
349+
ExampleModel: {
350+
DEFINE1: "D1",
351+
DEFINE2: "D2",
352+
DEFINE3: "D3",
353+
DEFINES: [["D1", "Define 1"], ["D2", "Define 2"], ["D3", "Define 3"]]
354+
}
355+
};
356356
```

0 commit comments

Comments
 (0)