52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
# Instructions
|
|
Here are special rules you must follow:
|
|
1. All forms should use regular form url encoding.
|
|
2. All routes should return html.
|
|
3. Use htmx for all dynamic content, when possible.
|
|
4. Use alpinejs for other dynamic content. For example, hiding or showing an element.
|
|
5. Prefer using daisyui over raw tailwind where possible.
|
|
6. Prefer using alpinejs over raw javascript. Raw javascript should almost never be needed.
|
|
7. Always print unhandled exceptions to the console.
|
|
8. Follow best practices for jinja template partials. That is, separate out components where appropriate.
|
|
9. Ask the user when there is something unclear.
|
|
10. I always run the server locally on port 5000, so you can use curl to test. No need to start it yourself.
|
|
11. Design docs go into docs/design/*.md. These docs are always kept up to date.
|
|
12. Before completing work, ensure that no design docs are left out of sync
|
|
13. Plans go into docs/plans/*.md. These may not be kept in sync, as they are just for brainstorming.
|
|
14. ****IMPORTANT**** Database migrations are automatically created via `flask db migrate -m 'message'`. **NEVER** create migrations by hand. You should never have to read the contents of migrations/
|
|
15. In the technical documentation, code should be used sparingly. Also, when needed, focus on the APIs, and only use snippets.
|
|
|
|
|
|
# Conventions
|
|
1. modals are rendered server-side, by targeting #modal-holder, and using an hx-trigger response attribute for open-modal.
|
|
2. modals are closed by adding the close-modal hx-trigger response attribute.
|
|
3. modals can be closed by triggering a close-modal event anywhere in the dom.
|
|
4. validation is done server-side. On modals, an error should cause the button to shake, and the invalid fields to be highlighted in red using normal daisyui paradigms. When relevant, there should be a notification banner inside the dialog-box to show the details of the error.
|
|
5. When validation is done outside of a modal, it should cause a notification banner with the details.
|
|
6. Testing is done with pytest.
|
|
7. Testing is done with beautifulsoup4
|
|
8. Only use comments where necessary. Prefer self-documenting code. For example:
|
|
```
|
|
is_adult = age >= 18
|
|
```
|
|
is preferred, and this is less preferred:
|
|
```
|
|
# check if the user is an adult
|
|
x = age >= 18
|
|
```
|
|
|
|
9. Buttons should be disabled, and a spinner should replace the icon content when loading. Only the button that was clicked should be disabled though. Typically this is done something like this:
|
|
```
|
|
<div data-loading-states>
|
|
<button class="..." hx-get="..." data-loading-disable>
|
|
<i class="fas fa-cog mr-2" data-loading-class="!hidden"></i>
|
|
<span data-loading-class="!hidden">Click Me!</span>
|
|
<span class="loading loading-spinner loading-xs hidden" data-loading-class-remove="hidden"></span> </button>
|
|
</div>
|
|
```
|
|
This will scope the disable to just the button, and disabled the button from being clicked. When in a modal, the whole modal should be disabled.
|
|
|
|
### context7 documentation library ids:
|
|
* HTMX: /bigskysoftware/htmx
|
|
* HTMX extensions: /bigskysoftware/htmx-extensions
|