Skip to content

Commit d638707

Browse files
youzarsiphyouzarsiph
committed
fix typo in README
1 parent 9765cc6 commit d638707

File tree

2 files changed

+381
-393
lines changed

2 files changed

+381
-393
lines changed

‎GUIDES.md‎

Lines changed: 375 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,375 @@
1+
# Customization Guides
2+
3+
To customize `drf-restwind`, follow these steps:
4+
5+
1. **Add Required Templates**:
6+
7+
In your app's templates directory, create a folder named `rest_framework` and
8+
add a file called `api.html`:
9+
10+
```bash
11+
mkdir app/templates/rest_framework
12+
touch app/templates/rest_framework/api.html
13+
```
14+
15+
2. **Populate Your Template**:
16+
17+
In `api.html`, include the following line:
18+
19+
```html
20+
{% extends 'rest_framework/base.html' %}
21+
```
22+
23+
3. **Add your `app` to `INSTALLED_APPS`**
24+
25+
In `project/settings.py`:
26+
27+
```python
28+
# Application definition
29+
INSTALLED_APPS = [
30+
# Add your app
31+
"app",
32+
"rest_wind",
33+
"rest_framework",
34+
...
35+
]
36+
```
37+
38+
Now you can proceed with the following customization guides.
39+
40+
## Customizing the Brand and Adding Links
41+
42+
To change the brand name and add custom links, modify your `api.html`:
43+
44+
```html
45+
{% extends 'rest_framework/base.html' %}{% load i18n %}
46+
47+
<!---->
48+
{% block title %}{% trans 'YOUR_BRAND' %}{% endblock %}
49+
50+
<!-- Branding -->
51+
{% block branding %}
52+
<li
53+
class="tooltip tooltip-right tooltip-primary rtl:tooltip-left"
54+
data-tip="{% trans 'YOUR_BRAND' %}"
55+
>
56+
<a
57+
href="https://your.domain.com/"
58+
class="btn btn-sm btn-square btn-ghost lg:btn-md"
59+
>
60+
<img
61+
class="size-8 2xl:size-10"
62+
alt="{% trans 'YOUR_BRAND' %}"
63+
src="{% static 'path/to/your/logo.png' %}"
64+
/>
65+
</a>
66+
</li>
67+
{% endblock %}
68+
69+
<!-- Add your brand text -->
70+
{% block drawer_branding %}
71+
<li
72+
class="tooltip tooltip-right tooltip-primary rtl:tooltip-left"
73+
data-tip="{% trans 'YOUR_BRAND' %}"
74+
>
75+
<a
76+
href="https://your.domain.com/"
77+
class="btn btn-sm btn-square btn-ghost lg:btn-md"
78+
>
79+
<img
80+
class="size-8 2xl:size-10"
81+
alt="{% trans 'YOUR_BRAND' %}"
82+
src="{% static 'path/to/your/logo.png' %}"
83+
/>
84+
</a>
85+
</li>
86+
{% endblock %}
87+
88+
<!-- Add your links -->
89+
{% block user_links %}
90+
<li
91+
class="is-drawer-close:tooltip is-drawer-close:tooltip-right rtl:is-drawer-close:tooltip-left"
92+
data-tip="{% trans 'Home' %}"
93+
>
94+
<a href="https://your.domain.com/">
95+
<i data-lucide="home" class="size-4 lg:size-6"></i>
96+
<span class="is-drawer-close:sr-only"> {% trans 'Home' %} </span>
97+
</a>
98+
</li>
99+
{% endblock %}
100+
```
101+
102+
```html
103+
<!-- rest_framework/login.html -->
104+
{% extends 'rest_framework/login_base.html' %}
105+
106+
<!-- Branding -->
107+
{% block branding %}
108+
<li
109+
class="tooltip tooltip-right tooltip-primary rtl:tooltip-left"
110+
data-tip="{% trans 'YOUR_BRAND' %}"
111+
>
112+
<a
113+
href="https://your.domain.com/"
114+
class="btn btn-sm btn-square btn-ghost lg:btn-md"
115+
>
116+
<img
117+
class="size-8 2xl:size-10"
118+
alt="{% trans 'YOUR_BRAND' %}"
119+
src="{% static 'path/to/your/logo.png' %}"
120+
/>
121+
</a>
122+
</li>
123+
{% endblock %}
124+
```
125+
126+
## Changing the Theme
127+
128+
You can view all available themes on [daisyUI](https://daisyui.com/) website. To
129+
modify the theme, update your `api.html`:
130+
131+
```html
132+
{% extends 'rest_framework/base.html' %}
133+
134+
<!-- Main theme -->
135+
{% block theme %}luxury{% endblock %}
136+
137+
<!-- Light or Dark theme to toggle between -->
138+
{% block toggle_theme %}silk{% endblock %}
139+
140+
<!-- Set the highlight_theme accordingly -->
141+
{% block highlight_theme %}
142+
<link
143+
rel="stylesheet"
144+
href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/base16/github-dark.min.css"
145+
/>
146+
{% endblock %}
147+
```
148+
149+
If you want to update code highlight theme for API documentation (written in
150+
`Markdown` in `View`'s `docstring`):
151+
152+
- Install `markdown` and `pygments`:
153+
154+
```console
155+
pip install markdown pygments
156+
```
157+
158+
- Select a style form available [styles](https://pygments.org/styles).
159+
- Generate the `css` file for selected styles:
160+
161+
```console
162+
pygmentize -S github-dark -f html > app/static/app/css/highlight.css
163+
```
164+
165+
- Include the generated `css` file in your `api.html`:
166+
167+
```html
168+
{% extends 'rest_framework/base.html' %}{% load static %}
169+
170+
<!-- Main theme -->
171+
{% block theme %}luxury{% endblock %}
172+
173+
<!-- Light or Dark theme to toggle between -->
174+
{% block toggle_theme %}silk{% endblock %}
175+
176+
<!-- Set the highlight_theme accordingly -->
177+
{% block highlight_theme %}
178+
<link
179+
rel="stylesheet"
180+
href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/base16/github-dark.min.css"
181+
/>
182+
183+
<!-- Include styles -->
184+
<link rel="stylesheet" href="{% static 'app/css/highlight.css' %}" />
185+
{% endblock %}
186+
```
187+
188+
## Creating your own theme
189+
190+
Can not find what you are looking for? Create your own theme:
191+
192+
1. Go to daisyUI [theme generator](https://daisyui.com/theme-generator/).
193+
2. Select a theme or Click the `Random` button to generate a random theme.
194+
3. Customize the defaults.
195+
4. After customization click the `CSS` button to copy CSS variables.
196+
5. Follow the steps:
197+
- Create `static` folder in your `app`:
198+
199+
```console
200+
mkdir -p app/static/app
201+
cd app/static/app
202+
```
203+
204+
- Install dependencies:
205+
206+
```console
207+
npm install tailwindcss '@tailwindcss/cli'
208+
npm install -D daisyui
209+
```
210+
211+
- Create your `css` folder and `styles`:
212+
213+
```console
214+
mkdir css
215+
touch css/app.css
216+
```
217+
218+
- Open your `app.css` and add the following lines:
219+
220+
```css
221+
@import "tailwindcss";
222+
223+
@plugin "daisyui";
224+
225+
/* Add your customized theme here */
226+
@plugin "daisyui/theme" {
227+
name: "lemon";
228+
default: false;
229+
prefersdark: false;
230+
color-scheme: "light";
231+
--color-base-100: oklch(98% 0.031 120.757);
232+
--color-base-200: oklch(96% 0.067 122.328);
233+
--color-base-300: oklch(93% 0.127 124.321);
234+
--color-base-content: oklch(40% 0.101 131.063);
235+
--color-primary: oklch(0% 0 0);
236+
--color-primary-content: oklch(100% 0 0);
237+
--color-secondary: oklch(62% 0.265 303.9);
238+
--color-secondary-content: oklch(97% 0.014 308.299);
239+
--color-accent: oklch(55% 0.013 58.071);
240+
--color-accent-content: oklch(98% 0.001 106.423);
241+
--color-neutral: oklch(40% 0.101 131.063);
242+
--color-neutral-content: oklch(98% 0.031 120.757);
243+
--color-info: oklch(78% 0.154 211.53);
244+
--color-info-content: oklch(30% 0.056 229.695);
245+
--color-success: oklch(84% 0.238 128.85);
246+
--color-success-content: oklch(27% 0.072 132.109);
247+
--color-warning: oklch(75% 0.183 55.934);
248+
--color-warning-content: oklch(26% 0.079 36.259);
249+
--color-error: oklch(71% 0.202 349.761);
250+
--color-error-content: oklch(28% 0.109 3.907);
251+
--radius-selector: 2rem;
252+
--radius-field: 0rem;
253+
--radius-box: 2rem;
254+
--size-selector: 0.25rem;
255+
--size-field: 0.25rem;
256+
--border: 1.5px;
257+
--depth: 1;
258+
--noise: 0;
259+
}
260+
```
261+
262+
- Generate your `styles`:
263+
264+
```console
265+
npx @tailwindcss/cli -i css/app.css -o css/styles.css
266+
```
267+
268+
- Include your `styles.css` in your templates:
269+
270+
```html
271+
{% extends 'rest_framework/base.html' %}{% load static %}
272+
273+
<!-- Add your styles -->
274+
{% block styles %} {{ block.super }}
275+
<link rel="stylesheet" href="{% static 'app/css/styles.css' %}" />
276+
{% endblock %}
277+
278+
<!-- Your custom theme -->
279+
{% block theme %}lemon{% endblock %}
280+
```
281+
282+
- Run your app to view the result.
283+
284+
Now, you have a theme that matches your brand.
285+
286+
## Removing package details
287+
288+
Update your `api.html`:
289+
290+
```html
291+
{% extends 'rest_framework/base.html' %}
292+
293+
<!---->
294+
{% block package %}{% endblock %}
295+
```
296+
297+
## Removing theme selector
298+
299+
To remove the theme selector, update your `api.html`:
300+
301+
```html
302+
{% extends 'rest_framework/base.html' %}
303+
304+
<!---->
305+
{% block theme_selector %}{% endblock %}
306+
```
307+
308+
```html
309+
<!-- rest_framework/login.html -->
310+
{% extends 'rest_framework/login_base.html' %} {% block theme_selector %}{%
311+
endblock %}
312+
```
313+
314+
## Removing the search bar
315+
316+
To remove the search bar, update your `api.html`:
317+
318+
```html
319+
{% extends 'rest_framework/base.html' %}
320+
321+
<!---->
322+
{% block navbar_center %}{% endblock %}
323+
```
324+
325+
## Removing theme toggle
326+
327+
To remove theme toggle, update your `api.html`:
328+
329+
```html
330+
{% extends 'rest_framework/base.html' %}
331+
332+
<!---->
333+
{% block theme_toggle %}{% endblock %}
334+
```
335+
336+
```html
337+
<!-- rest_framework/login.html -->
338+
{% extends 'rest_framework/login_base.html' %} {% block theme_selector %}{%
339+
endblock %}
340+
```
341+
342+
## Adding menu items to profile menu
343+
344+
To add menu items to profile menu, modify your `api.html`:
345+
346+
```html
347+
{% extends 'rest_framework/base.html' %}{% load i18n %}
348+
349+
<!---->
350+
{% block profile_links %}
351+
<li
352+
class="is-drawer-close:tooltip is-drawer-close:tooltip-right rtl:is-drawer-close:tooltip-left"
353+
data-tip="{% trans 'Profile' %}"
354+
>
355+
<a href="https://your.domain.com/me/">
356+
<i data-lucide="user" class="size-4 lg:size-6"></i>
357+
<span class="is-drawer-close:sr-only"> {% trans 'Profile' %} </span>
358+
</a>
359+
</li>
360+
{% endblock %}
361+
```
362+
363+
## Generating CSS styles
364+
365+
To generate the CSS styles, run:
366+
367+
```console
368+
cd rest_wind/static/rest_wind
369+
370+
# Install deps
371+
npm install
372+
373+
# Generate the styles using TailwindCSS
374+
npx @tailwindcss/cli -i ../static/rest_wind/css/app.css -o ../static/rest_wind/css/styles.css --cwd ../../templates -m
375+
```

0 commit comments

Comments
 (0)