Skip to content

Commit cdd1470

Browse files
Merge pull request #88 from Promptly-Technologies-LLC/46-document-how-to-do-frontend-bootstrap-styling-in-customization-docs
46 document how to do frontend bootstrap styling in customization docs
2 parents 10db84d + 8297b3e commit cdd1470

File tree

6 files changed

+11951
-5
lines changed

6 files changed

+11951
-5
lines changed

.gitignore

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,8 @@ __pycache__
66
_docs/
77
.pytest_cache/
88
.mypy_cache/
9-
.cursorrules
9+
node_modules
10+
package-lock.json
11+
package.json
12+
.specstory
13+
.cursorrules

docs/customization.qmd

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ We have also exposed the full Markdown-formatted project documentation as a [sin
7272
- Organization management endpoints: `organization.py`
7373
- Role management endpoints: `role.py`
7474
- Jinja2 templates: `templates/`
75+
- Bootstrap Sass Files: `scss/`
7576
- Static assets: `static/`
7677
- Unit tests: `tests/`
7778
- Test database configuration: `docker-compose.yml`
@@ -116,6 +117,101 @@ To generate the HTML pages to be returned from our GET routes, we use Jinja2 tem
116117

117118
With Jinja2, we can use the `{% block %}` tag to define content blocks, and the `{% extends %}` tag to extend a base template. We can also use the `{% include %}` tag to include a component in a parent template. See the [Jinja2 documentation on template inheritance](https://jinja.palletsprojects.com/en/stable/templates/#template-inheritance) for more details.
118119

120+
### Custom theming with Bootstrap Sass
121+
122+
[Install Node.js](https://nodejs.org/en/download/) on your local machine if it is not there already.
123+
124+
Install `bootstrap`, `sass`, `gulp`, and `gulp-sass` in your project:
125+
126+
```bash
127+
npm install --save-dev bootstrap sass gulp gulp-cli gulp-sass
128+
```
129+
130+
This will create a `node_modules` folder, a `package-lock.json` file, and a `package.json` file in the root directory of the project.
131+
132+
Create an `scss` folder and a basic `scss/styles.scss` file:
133+
134+
```bash
135+
mkdir scss
136+
touch scss/styles.scss
137+
```
138+
139+
Your custom styles will go in `scss/styles.scss`, along with `@import` statements to include the Bootstrap components you want. For example, the default CSS for the template was compiled from the following configuration, which imports all of Bootstrap and overrides the `$theme-colors` and `$font-family-base` variables:
140+
141+
```scss
142+
// styles.scss
143+
144+
// Include any default variable overrides here (functions won't be available)
145+
146+
// State colors
147+
$primary: #7464a1;
148+
$secondary: #64a19d;
149+
$success: #67c29c;
150+
$info: #1cabc4;
151+
$warning: #e4c662;
152+
$danger: #a16468;
153+
$light: #f8f9fa;
154+
$dark: #343a40;
155+
156+
// Bootstrap color map
157+
$theme-colors: (
158+
"primary": $primary,
159+
"secondary": $secondary,
160+
"success": $success,
161+
"info": $info,
162+
"warning": $warning,
163+
"danger": $danger,
164+
"light": $light,
165+
"dark": $dark
166+
);
167+
168+
$font-family-base: (
169+
"Nunito",
170+
-apple-system,
171+
BlinkMacSystemFont,
172+
"Segoe UI",
173+
Roboto,
174+
"Helvetica Neue",
175+
Arial,
176+
sans-serif,
177+
"Apple Color Emoji",
178+
"Segoe UI Emoji",
179+
"Segoe UI Symbol",
180+
"Noto Color Emoji"
181+
);
182+
183+
// Include all of Bootstrap
184+
185+
@import "../node_modules/bootstrap/scss/bootstrap";
186+
```
187+
188+
The most common use case for `styles.scss` is to define a custom color scheme and fonts, but it's also possible to other visual details such as border radius and box shadow depth. See the [Bootstrap Sass customization instructions](https://getbootstrap.com/docs/5.3/customize/sass/) and the many free templates available at [Start Bootstrap](https://startbootstrap.com) for examples.
189+
190+
To compile the Sass files, we use `gulp`. In the project root directory, create a `gulpfile.js` file with the following content:
191+
192+
```javascript
193+
const gulp = require('gulp');
194+
const sass = require('gulp-sass')(require('sass'));
195+
196+
// Define a task to compile Sass
197+
gulp.task('sass', function() {
198+
return gulp.src('scss/**/*.scss') // Source folder containing Sass files
199+
.pipe(sass().on('error', sass.logError))
200+
.pipe(gulp.dest('static/css')); // Destination folder for compiled CSS
201+
});
202+
203+
// Define a default task
204+
gulp.task('default', gulp.series('sass'));
205+
```
206+
207+
To compile the Sass file to `static/css`, run this command:
208+
209+
```bash
210+
npx gulp
211+
```
212+
213+
Note that this will overwrite the existing `static/css/styles.css` file, so if you want to define any custom CSS styles, you should do so in either the `scss/styles.scss` file or in `static/css/extras.css`.
214+
119215
#### Context variables
120216

121217
Context refers to Python variables passed to a template to populate the HTML. In a FastAPI GET route, we can pass context to a template using the `templates.TemplateResponse` method, which takes the request and any context data as arguments. For example:
@@ -136,6 +232,7 @@ In this example, the `welcome.html` template will receive two pieces of context:
136232
While this template includes comprehensive server-side validation through Pydantic models and custom validators, it's important to note that server-side validation should be treated as a fallback security measure. If users ever see the `validation_error.html` template, it indicates that our client-side validation has failed to catch invalid input before it reaches the server.
137233

138234
Best practices dictate implementing thorough client-side validation via JavaScript and/or HTML `input` element `pattern` attributes to:
235+
139236
- Provide immediate feedback to users
140237
- Reduce server load
141238
- Improve user experience by avoiding round-trips to the server

docs/installation.qmd

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ If you use VSCode with Docker to develop in a container, the following VSCode De
1010
{
1111
"name": "Python 3",
1212
"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bookworm",
13-
"postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz libwebp-dev && uv venv && uv sync",
13+
"postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz libwebp-dev && npm install [email protected] && npm install -g sass && npm install -g gulp && uv venv && uv sync",
1414
"features": {
1515
"ghcr.io/va-h/devcontainers-features/uv:1": {
1616
"version": "latest"
File renamed without changes.

0 commit comments

Comments
 (0)