Skip to main content

​
Controllers Overview

Controllers are the core building blocks of your Framefox application. They handle incoming HTTP requests, process business logic, and return responses to the client.

​
AbstractController Class

All controllers in Framefox should extend the AbstractController class, which provides essential methods for handling HTTP requests and responses. 
from framefox.core.controller.abstract_controller import AbstractController

class HomeController(AbstractController):
    def __init__(self):
        super().__init__()
The AbstractController automatically initializes:
  • Service Container: For dependency injection
  • Template Renderer: For rendering HTML templates

​
Creating a Controller

Create a new controller by extending AbstractController: 
from framefox.core.controller.abstract_controller import AbstractController
from framefox.core.routing.decorator.route import Route

class UserController(AbstractController):
    @Route(path="/users", name="user_list", methods=["GET"])
    async def list_users(self):
        users = [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}]
        return self.render("users/list.html", {"users": users})

​
Controller Methods

The AbstractController provides several built-in methods for handling common operations.

​
render()

Renders an HTML template with optional context data.
​
template_path
str
required
Path to the template file to render
​
context
dict
default:"None"
Data to pass to the template
Returns: HTMLResponse 
@Route(path="/welcome", name="welcome", methods=["GET"])
async def welcome(self):
    return self.render("welcome.html", {
        "title": "Welcome to Framefox",
        "user": "Alice"
    })

​
json()

Returns data as a JSON response.
​
data
dict
required
The data to serialize as JSON
​
status
int
default:"200"
HTTP status code for the response
Returns: JSONResponse 
@Route(path="/api/users/{user_id}", name="api_user", methods=["GET"])
async def get_user_api(self, user_id: int):
    user = {"id": user_id, "name": "John Doe", "email": "[email protected]"}
    return self.json(user)

​
redirect()

Redirects the user to a specific URL.
​
location
str
required
The URL to redirect to
​
code
int
default:"302"
HTTP status code for the redirect
Returns: RedirectResponse 
@Route(path="/old-page", name="old_page", methods=["GET"])
async def old_page(self):
    return self.redirect("/new-page", code=301)

​
flash()

Adds a flash message to the session for displaying on the next request.
​
category
str
required
The category/type of the flash message (e.g., ‘success’, ‘error’, ‘warning’)
​
message
str
required
The message content to display
@Route(path="/save", name="save_data", methods=["POST"])
async def save_data(self):
    # Save data logic here
    self.flash("success", "Data saved successfully!")
    return self.redirect("/dashboard")

​
get_user()

Retrieves the currently authenticated user.
​
user_class
class
default:"None"
Specific user class to cast the result to
Returns: User instance or None if not authenticated 
@Route(path="/profile", name="user_profile", methods=["GET"])
async def profile(self):
    user = self.get_user()
    if not user:
        return self.redirect("/login")
    
    return self.render("profile.html", {"user": user})

​
generate_url()

Generates a URL for a named route with optional parameters.
​
route_name
str
required
The name of the route to generate URL for
​
**params
Any
Additional parameters to include in the URL
Returns: str - The generated URL 
@Route(path="/user/{user_id}", name="user_detail", methods=["GET"])
async def user_detail(self, user_id: int):
    # Generate URL for another route
    edit_url = self.generate_url("user_edit", user_id=user_id)
    
    return self.render("user/detail.html", {
        "user_id": user_id,
        "edit_url": edit_url
    })

​
create_form()

Creates a form instance from a form type class and binds it to an entity.
​
form_type_class
class
required
The form class to instantiate
​
entity_instance
object
required
The entity object to bind to the form
Returns: Form instance 
from app.forms.user_form import UserForm
from app.models.user import User

@Route(path="/user/edit/{user_id}", name="user_edit", methods=["GET", "POST"])
async def edit_user(self, user_id: int, request: Request):
    user = User.get_by_id(user_id)
    form = self.create_form(UserForm, user)
    
    if await form.handle_request(request):
        # Form is valid, save the user
        self.flash("success", "User updated successfully!")
        return self.redirect("/users")
    
    return self.render("user/edit.html", {"form": form.create_view()})

​
Next Steps

Routing

Learn how to define routes for your controllers

Responses

Explore different response types

Forms

Work with forms and validation

Build docs developers (and LLMs) love

Get started for freeTalk to us