179 lines
5.3 KiB
Markdown
179 lines
5.3 KiB
Markdown
# MyFastHtml
|
||
|
||
A utility library designed to simplify the development of FastHtml applications by providing:
|
||
- Predefined pages for common functionalities (e.g., authentication, user management).
|
||
- A command management system to facilitate client-server interactions.
|
||
- Helpers to create interactive controls more easily.
|
||
- A system for control state persistence.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- **Dynamic HTML with HTMX**: Simplify dynamic interaction using attributes like `hx-post` and custom routes like `/commands`.
|
||
- **Command management**: Write server-side logic in Python while abstracting the complexities of HTMX.
|
||
- **Control helpers**: Easily create reusable components like buttons.
|
||
- **Predefined Pages (Roadmap)**: Include common pages like login, user management, and customizable dashboards.
|
||
|
||
> _**Note:** Support for state persistence is currently under construction._
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
Ensure you have Python >= 3.12 installed, then install the library with `pip`:
|
||
|
||
```bash
|
||
pip install myfasthtml
|
||
```
|
||
|
||
---
|
||
|
||
## Quick Start
|
||
|
||
Here’s a simple example of creating an **interactive button** linked to a command:
|
||
|
||
### Example: Button with a Command
|
||
|
||
```python
|
||
from fasthtml.fastapp import fast_app
|
||
from myfasthtml.core.commands import Command
|
||
from myfasthtml.controls.button import mk_button
|
||
|
||
# Define a simple command action
|
||
def say_hello():
|
||
return "Hello, FastHtml!"
|
||
|
||
# Create the command
|
||
hello_command = Command("say_hello", "Responds with a greeting", say_hello)
|
||
|
||
# Create the app and define a route with a button
|
||
app, rt = fast_app(default_hdrs=False)
|
||
|
||
@rt("/")
|
||
def get_homepage():
|
||
return mk_button("Click Me!", command=hello_command)
|
||
```
|
||
|
||
- When the button is clicked, the `say_hello` command will be executed, and the server will return the response.
|
||
- HTMX automatically handles the client-server interaction behind the scenes.
|
||
|
||
---
|
||
|
||
## Planned Features (Roadmap)
|
||
|
||
### Predefined Pages
|
||
The library will include predefined pages for:
|
||
- **Authentication**: Login, signup, password reset.
|
||
- **User Management**: User profile and administration pages.
|
||
- **Dashboard Templates**: Fully customizable dashboard components.
|
||
- **Error Pages**: Detailed and styled error messages (e.g., 404, 500).
|
||
|
||
### State Persistence
|
||
Controls will have their state automatically synchronized between the client and the server. This feature is currently under construction.
|
||
|
||
---
|
||
|
||
## Advanced Features
|
||
|
||
### Command Management System
|
||
Commands allow you to simplify frontend/backend interaction. Instead of writing HTMX attributes manually, you can define Python methods and handle them as commands.
|
||
|
||
#### Example
|
||
Here’s how `Command` simplifies dynamic interaction:
|
||
|
||
```python
|
||
from myfasthtml.core.commands import Command
|
||
|
||
# Define a command
|
||
def custom_action(data):
|
||
return f"Received: {data}"
|
||
|
||
my_command = Command("custom", "Handles custom logic", custom_action)
|
||
|
||
# Get the HTMX parameters automatically
|
||
htmx_attrs = my_command.get_htmx_params()
|
||
print(htmx_attrs)
|
||
|
||
# Output:
|
||
# {
|
||
# "hx-post": "/commands",
|
||
# "hx-vals": '{"c_id": "unique-command-id"}'
|
||
# }
|
||
```
|
||
|
||
Use the `get_htmx_params()` method to directly integrate commands into HTML components.
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
We welcome contributions! To get started:
|
||
1. Fork the repository.
|
||
2. Create a feature branch.
|
||
3. Submit a pull request with clear descriptions of your changes.
|
||
|
||
For detailed guidelines, see the [Contributing Section](./CONTRIBUTING.md) (coming soon).
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
This project is licensed under the terms of the MIT License. See the `LICENSE` file for details.
|
||
|
||
---
|
||
|
||
## Technical Overview
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
MyFastHtml
|
||
├── src
|
||
│ ├── myfasthtml/ # Main library code
|
||
│ │ ├── core/commands.py # Command definitions
|
||
│ │ ├── controls/button.py # Control helpers
|
||
│ │ └── pages/LoginPage.py # Predefined Login page
|
||
│ └── ...
|
||
├── tests # Unit and integration tests
|
||
├── LICENSE # License file (MIT)
|
||
├── README.md # Project documentation
|
||
└── pyproject.toml # Build configuration
|
||
```
|
||
|
||
### Notable Classes and Methods
|
||
|
||
#### 1. `Command`
|
||
Represents a backend action with server communication.
|
||
- **Attributes:**
|
||
- `id`: Unique identifier for the command.
|
||
- `name`: Command name (e.g., `say_hello`).
|
||
- `description`: Description of the command.
|
||
- **Method:** `get_htmx_params()` generates HTMX attributes.
|
||
|
||
#### 2. `mk_button`
|
||
Simplifies the creation of interactive buttons linked to commands.
|
||
- **Arguments:**
|
||
- `element` (str): The label for the button.
|
||
- `command` (Command): Command associated with the button.
|
||
- `kwargs`: Additional button attributes.
|
||
|
||
#### 3. `LoginPage`
|
||
Predefined login page that provides a UI template ready for integration.
|
||
- **Constructor Parameters:**
|
||
- `settings_manager`: Configuration/settings object.
|
||
- `error_message`: Optional error message to display.
|
||
- `success_message`: Optional success message to display.
|
||
|
||
---
|
||
|
||
## Entry Points
|
||
|
||
- `/commands`: Handles HTMX requests from the command attributes.
|
||
|
||
---
|
||
|
||
## Exceptions
|
||
|
||
No custom exceptions defined yet. (Placeholder for future use.)
|
||
``` |